Plugins¶

def plugin_method(
    label: Optional[str] = None,
    description: Optional[str] = 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__, label=label, description=description)
        method_hints = get_type_hints(func, include_extras=True)

        for arg_name, hint in method_hints.items():
            base_type, annotation = extract_info(hint)

            if not isinstance(base_type, type) or arg_name == "return":
                continue

            if issubclass(base_type, PluginInput):
                plugin_method_meta._input_model = base_type
            elif issubclass(base_type, OCEL):
                plugin_method_meta.input_ocels[arg_name] = (
                    OCELAnnotation(**annotation.model_dump())
                    if annotation is not None
                    else OCELAnnotation(label=arg_name)
                )
            elif issubclass(base_type, Resource):
                plugin_method_meta._resource_types.add(base_type)

                plugin_method_meta.input_resources[arg_name] = (
                    base_type.get_type(),
                    ResourceAnnotation(**annotation.model_dump())
                    if annotation is not None
                    else ResourceAnnotation(label=arg_name),
                )
            else:
                raise TypeError(
                    f"Argument {arg_name} must be either an OCEL, Resource or Input Schema"
                )

        return_type = method_hints.get("return", None)

        if return_type is not None:
            origin = get_origin(return_type)

            types_to_parse = []

            if origin is tuple:
                types_to_parse = get_args(return_type)
            else:
                types_to_parse = [return_type]

            for typ in types_to_parse:
                base_type, annotation = extract_info(typ)

                if get_origin(base_type) is list:
                    inner_type = get_args(base_type)[0]
                    base_type, annotation = extract_info(inner_type)
                    is_list = True
                else:
                    is_list = False

                # Now determine what kind of result it is
                if issubclass(base_type, OCEL):
                    plugin_method_meta.results.append(
                        OCELResult(
                            type="ocel",
                            is_list=is_list,
                            annotation=OCELAnnotation(**annotation.model_dump())
                            if annotation is not None
                            else None,
                        )
                    )
                elif issubclass(base_type, Resource):
                    plugin_method_meta._resource_types.add(base_type)

                    annotation_obj = (
                        annotation if isinstance(annotation, ResourceAnnotation) else None
                    )
                    if annotation_obj and annotation_obj.annotation_resources:
                        plugin_method_meta._resource_types.update(
                            annotation_obj.annotation_resources
                        )

                    plugin_method_meta.results.append(
                        ResourceResult(
                            type="resource",
                            is_list=is_list,
                            annotation=annotation_obj,
                            resource_type=base_type.get_type(),
                        )
                    )
                else:
                    raise TypeError(f"Unsupported return type: {base_type}")

        plugin_method_meta._method = func

        setattr(
            func,
            "__meta__",
            plugin_method_meta,
        )

        return func

    return decorator

def OCEL_FIELD(
    *,
    field_type: Literal[
        "object_type",
        "event_type",
        "event_id",
        "object_id",
        "event_attribute",
        "object_attribute",
        "time_frame",
    ],
    ocel_id: str,
    default: Any = ...,
    title: Optional[str] = None,
    description: Optional[str] = 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,
    }

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

def COMPUTED_SELECTION(
    *,
    title: Optional[str] = None,
    description: Optional[str] = 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},
    )