ocelescope-module-plugin 0.12.0__py3-none-any.whl

ocelescope_module_plugin/archive.py

@@ -0,0 +1,99 @@
+import shutil
+import tempfile
+import traceback
+import zipfile
+from pathlib import Path, PurePosixPath
+from uuid import uuid4
+
+from ocelescope_backend.app.internal.config import config as backend_config
+from ocelescope_backend.app.internal.util.archive import extract_archive, is_ignored
+from ocelescope_backend.app.sse_manager import (
+    ErrorNotification,
+    InvalidationRequest,
+    SSEMessage,
+    SystemNotification,
+)
+
+from ocelescope_module_plugin.config import config
+from ocelescope_module_plugin.registry import PluginRegistry
+
+
+def is_plugin_archive(archive: zipfile.ZipFile) -> bool:
+    return any(
+        len(path.parts) == 2 and path.name == "__init__.py" and not is_ignored(path)
+        for path in map(PurePosixPath, archive.namelist())
+    )
+
+
+def import_plugin_archive(
+    registry: PluginRegistry, archive: zipfile.ZipFile, file_name: str
+) -> list[SSEMessage]:
+    if not config.PLUGIN_DIR:
+        raise RuntimeError("Plugin uploads are disabled on this deployment")
+
+    added_plugin_ids = []
+
+    with tempfile.TemporaryDirectory() as temp_dir:
+        extract_archive(
+            archive,
+            Path(temp_dir),
+            max_uncompressed_bytes=backend_config.ARCHIVE_MAX_UNCOMPRESSED_BYTES,
+        )
+
+        for plugin_candidate in Path(temp_dir).iterdir():
+            if (
+                plugin_candidate.is_dir()
+                and (plugin_candidate / "__init__.py").exists()
+            ):
+                plugin_id = f"plugin_{uuid4()!s}"
+                shutil.move(plugin_candidate, config.PLUGIN_DIR / plugin_id)
+                added_plugin_ids.append(plugin_id)
+
+    results: list[SSEMessage] = []
+    loaded_plugin_ids: list[str] = []
+    for plugin_id in added_plugin_ids:
+        try:
+            loaded_plugin_ids.extend(
+                registry.load_from_dir(
+                    config.PLUGIN_DIR, [plugin_id], ignore_errors=False
+                )
+            )
+        except Exception as exc:
+            results.append(
+                ErrorNotification(
+                    type="error",
+                    title=f"Error while uploading plugin {file_name}",
+                    message=str(exc),
+                    trace=traceback.format_exc(),
+                )
+            )
+
+    loaded_plugins = [
+        plugin.label
+        for id in loaded_plugin_ids
+        if (plugin := registry.get_plugin(id)) is not None
+    ]
+
+    if len(loaded_plugins) == 0:
+        if not results:
+            results.append(
+                SystemNotification(
+                    type="notification",
+                    title="Uploaded zip didn't contain any plugins",
+                    notification_type="error",
+                    message=f"The uploaded file {file_name} did not contain any valid plugins",
+                )
+            )
+        return results
+
+    results.extend(
+        [
+            SystemNotification(
+                title="Plugin successfully uploaded",
+                message=f"Successfully uploaded {' '.join(loaded_plugins)}",
+                notification_type="info",
+            ),
+            InvalidationRequest(routes=["plugins", "tasks", "discoveryMethods"]),
+        ]
+    )
+    return results

ocelescope_module_plugin/base_plugin.py

@@ -0,0 +1,105 @@
+from typing import Annotated
+
+from ocelescope.discovery import inductive_miner, ocdfg_miner
+
+from ocelescope import (
+    OCEL,
+    OCEL_FIELD,
+    SLIDER_FIELD,
+    DirectlyFollowsGraph,
+    OCELAnnotation,
+    PetriNet,
+    Plugin,
+    PluginInput,
+    ResourceAnnotation,
+    plugin_method,
+)
+
+Paths = Annotated[
+    float,
+    SLIDER_FIELD(
+        min=0.01,
+        max=1,
+        step=0.01,
+        default=0.5,
+        title="Paths",
+        description=(
+            "How many of the less frequent paths to include. "
+            "Lower values give a simpler model."
+        ),
+    ),
+]
+ObjectTypes = Annotated[
+    list[str],
+    OCEL_FIELD(
+        field_type="object_type",
+        ocel_id="ocel",
+        theme="r4pm",
+        title="Included object types",
+        description="Only these object types are used for discovery.",
+        default_frequency=0.5,
+    ),
+]
+Activities = Annotated[
+    list[str],
+    OCEL_FIELD(
+        field_type="event_type",
+        ocel_id="ocel",
+        theme="r4pm",
+        title="Included activities",
+        description="Only events of these activities are used for discovery.",
+        default_frequency=0.5,
+    ),
+]
+
+
+class DiscoveryPetriInput(PluginInput):
+    paths: Paths
+    object_types: ObjectTypes
+    activities: Activities
+
+
+class DiscoveryDFGInput(PluginInput):
+    paths: Paths
+    activities: Activities
+
+
+class BasePlugin(Plugin):
+    label = "Base Discovery"
+    description = "Discover object-centric process models from an event log."
+    version = "1.0.0"
+
+    @plugin_method(
+        label="Discover Directly-Follows Graph",
+        description="Discover an object-centric directly-follows graph.",
+    )
+    def discover_ocdfg(
+        self,
+        ocel: Annotated[OCEL, OCELAnnotation(label="Event log")],
+        input: DiscoveryDFGInput,
+    ) -> Annotated[
+        DirectlyFollowsGraph, ResourceAnnotation(label="Directly-Follows Graph")
+    ]:
+        ocdfg = ocdfg_miner(
+            ocel,
+            frequency_threshold=input.paths,
+            included_activities=input.activities,
+        )
+        return ocdfg
+
+    @plugin_method(
+        label="Discover Petri Net",
+        description="Discover an object-centric Petri net using the inductive miner.",
+    )
+    def discover_ocpn(
+        self,
+        ocel: Annotated[OCEL, OCELAnnotation(label="Event log")],
+        input: DiscoveryPetriInput,
+    ) -> Annotated[PetriNet, ResourceAnnotation(label="Petri Net")]:
+        return inductive_miner(
+            ocel,
+            # pm4py's noise threshold counts what to drop, the slider what to keep.
+            noise_threshold=1 - input.paths,
+            included_activities=input.activities,
+            included_object_types=input.object_types,
+        )

ocelescope_module_plugin/config.py

@@ -0,0 +1,14 @@
+from pydantic import DirectoryPath, Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class PluginModuleConfig(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+    PLUGIN_DIR: DirectoryPath | None = Field(
+        default=None,
+        description="Path to the directory, where plugins are stored",
+    )
+
+
+config = PluginModuleConfig()

ocelescope_module_plugin/dependencies.py

@@ -0,0 +1,27 @@
+from typing import Annotated
+
+from fastapi import Depends, Request
+from ocelescope_backend.app.dependencies import ApiSession
+from ocelescope_backend.app.internal.exceptions import NotFound
+
+from ocelescope_module_plugin.registry import PluginRegistry
+from ocelescope_module_plugin.tasks import PluginTask
+
+
+def get_plugin_registry(request: Request) -> PluginRegistry:
+    return request.app.state.plugin_registry
+
+
+ApiPluginRegistry = Annotated[PluginRegistry, Depends(get_plugin_registry)]
+
+
+def get_plugin_task(session: ApiSession, task_id: str) -> PluginTask:
+    plugin_task = session.get_task(task_id)
+
+    if plugin_task is None or not isinstance(plugin_task, PluginTask):
+        raise NotFound("Task could not be found")
+
+    return plugin_task
+
+
+ApiPluginTask = Annotated[PluginTask, Depends(get_plugin_task)]

ocelescope_module_plugin/dynamic_import.py

@@ -0,0 +1,56 @@
+import importlib
+import importlib.util
+import os
+import sys
+import tempfile
+import zipfile
+from pathlib import Path
+
+from packaging import tags
+from packaging.utils import parse_wheel_filename
+
+
+# TODO: Use packaging to make this more normed
+def import_wheel_dynamically(wheel_path: Path):
+    """
+    Dynamically loads a wheel (.whl) file if not already installed or imported.
+    Returns the loaded package module.
+    """
+    with zipfile.ZipFile(wheel_path, "r") as whl:
+        names = whl.namelist()
+        pkg_names = [n.split("/")[0] for n in names if n.endswith("__init__.py")]
+        if not pkg_names:
+            raise ImportError("No package found in wheel")
+        package_name = pkg_names[0]
+
+    if package_name in sys.modules:
+        return sys.modules[package_name]
+
+    if importlib.util.find_spec(package_name) is not None:
+        return importlib.import_module(package_name)
+
+    temp_dir = Path(tempfile.mkdtemp(prefix="dynwhl_"))
+    with zipfile.ZipFile(wheel_path, "r") as whl:
+        whl.extractall(temp_dir)
+
+    pkg_root = None
+    for root, _, files in os.walk(temp_dir):
+        if "__init__.py" in files:
+            pkg_root = Path(root)
+            break
+
+    if not pkg_root:
+        raise ImportError("No package with __init__.py found in wheel")
+
+    sys.path.insert(0, str(pkg_root.parent))
+
+    pkg = importlib.import_module(package_name)
+    return pkg
+
+
+def is_wheel_compatible(wheel_name: str):
+    _, _, _, wheel_tags = parse_wheel_filename(wheel_name)
+
+    supported_tag = set(tags.sys_tags())
+
+    return bool(supported_tag & wheel_tags)

ocelescope_module_plugin/hashing.py

@@ -0,0 +1,41 @@
+import dataclasses
+import hashlib
+from typing import Any
+
+import orjson
+from pydantic import BaseModel
+
+
+def normalize(obj: Any) -> Any:
+    """Recursively convert objects into JSON-serializable, deterministic forms."""
+    if isinstance(obj, BaseModel):
+        return normalize(obj.model_dump(serialize_as_any=True))
+
+    if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
+        return normalize(dataclasses.asdict(obj))
+
+    if isinstance(obj, dict):
+        return {str(k): normalize(v) for k, v in sorted(obj.items())}
+
+    if isinstance(obj, (list, tuple)):
+        return [normalize(v) for v in obj]
+
+    if isinstance(obj, set):
+        return sorted(normalize(v) for v in obj)
+
+    return obj
+
+
+def to_canonical_bytes(obj: Any) -> bytes:
+    """Serialize normalized object to canonical JSON bytes."""
+    normalized = normalize(obj)
+    return orjson.dumps(normalized, option=orjson.OPT_SORT_KEYS)
+
+
+def generate_tuple_hash(*args: Any) -> str:
+    """Generate a deterministic SHA-256 hash for arbitrary arguments."""
+    h = hashlib.sha256()
+    for arg in args:
+        h.update(to_canonical_bytes(arg))
+        h.update(b"\x00")
+    return h.hexdigest()

ocelescope_module_plugin/models/plugin.py

@@ -0,0 +1,97 @@
+from typing import Annotated, Any, Literal, Self
+
+from ocelescope.plugin.decorators import PluginIO
+from pydantic import BaseModel, Field
+
+from ocelescope import OCEL, Plugin, PluginMethod
+
+
+class PluginIOApiBase(BaseModel):
+    name: str
+    label: str
+    description: str | None
+    is_optional: bool
+    is_list: bool
+
+    @classmethod
+    def from_plugin_io(cls, io: PluginIO) -> Self:
+
+        return cls(
+            name=io.name,
+            label=io.label,
+            description=io.description,
+            is_optional=io.is_optional,
+            is_list=io.is_list,
+        )
+
+
+class OCELIOApi(PluginIOApiBase):
+    type: Literal["ocel"]
+
+
+class ResourceIOApi(PluginIOApiBase):
+    type: Literal["resource"]
+    schema_id: str
+    resource_label: str
+
+
+PluginIOApi = Annotated[OCELIOApi | ResourceIOApi, Field(discriminator="type")]
+
+
+def _plugin_io_to_api(io: PluginIO):
+    base = PluginIOApiBase.from_plugin_io(io)
+    return (
+        OCELIOApi(type="ocel", **base.model_dump())
+        if issubclass(io.type, OCEL)
+        else ResourceIOApi(
+            type="resource",
+            schema_id=io.type.get_schema_hash(),
+            resource_label=io.type.get_label(),
+            **base.model_dump(),
+        )
+    )
+
+
+class MethodApi(BaseModel):
+    name: str
+    label: str
+    description: str | None = None
+    inputs: list[PluginIOApi]
+    outputs: list[PluginIOApi]
+    configuration_schema: dict[str, Any] | None = None
+
+    @classmethod
+    def from_method_meta(cls, method: PluginMethod) -> Self:
+        return cls(
+            name=method.name,
+            label=method.label,
+            description=method.description,
+            inputs=[_plugin_io_to_api(io) for io in method.inputs],
+            outputs=[_plugin_io_to_api(io) for io in method.outputs],
+            configuration_schema=method.configuration_input.model_json_schema()
+            if method.configuration_input
+            else None,
+        )
+
+
+class PluginApi(BaseModel):
+    id: str
+    name: str
+    version: str
+    label: str
+    description: str | None = None
+    methods: list[MethodApi]
+
+    @classmethod
+    def from_plugin(cls, id: str, plugin: Plugin) -> Self:
+        return cls(
+            id=id,
+            name=plugin.get_name(),
+            version=plugin.version,
+            label=plugin.label,
+            description=plugin.description,
+            methods=[
+                MethodApi.from_method_meta(method)
+                for method in plugin.method_map().values()
+            ],
+        )

ocelescope_module_plugin/models/plugin_result.py

@@ -0,0 +1,47 @@
+from typing import Literal, Self
+
+from pydantic import BaseModel
+
+from ocelescope_module_plugin.tasks import PluginTask
+
+
+class PluginOutput(BaseModel):
+    id: str
+    type: Literal["ocel", "resource"]
+    name: str
+    type_label: str
+    created_at: str
+
+    @classmethod
+    def from_task(cls, task: PluginTask) -> list[Self]:
+        session = task.session
+
+        ocels = [
+            cls(
+                id=ocel.id,
+                type="ocel",
+                name=ocel.name,
+                type_label="OCEL",
+                created_at=ocel.created_at,
+            )
+            for ocel in session.list_ocels(source_id=task.id, include_hidden=True)
+        ]
+        resources = [
+            cls(
+                id=resource.id,
+                type="resource",
+                name=resource.name,
+                type_label=resource.resource_type_label,
+                created_at=resource.created_at,
+            )
+            for resource in session.list_resources(
+                source_id=task.id, include_hidden=True
+            )
+        ]
+
+        return sorted([*ocels, *resources], key=lambda output: output.created_at)
+
+
+class ResultSelection(BaseModel):
+    id: str
+    name: str | None

ocelescope_module_plugin/module.py

@@ -0,0 +1,57 @@
+import zipfile
+from typing import TYPE_CHECKING
+
+from fastapi import FastAPI
+from ocelescope_backend.app.modules import Module, ModuleMeta
+from ocelescope_backend.app.modules.context import ModuleContext
+from ocelescope_backend.app.sse_manager import SSEMessage
+from packaging.version import Version
+
+from ocelescope_module_plugin.archive import import_plugin_archive, is_plugin_archive
+from ocelescope_module_plugin.base_plugin import BasePlugin
+from ocelescope_module_plugin.config import config
+from ocelescope_module_plugin.registry import PluginRegistry
+from ocelescope_module_plugin.routers import router
+
+if TYPE_CHECKING:
+    from ocelescope_backend.app.internal.session import Session
+    from ocelescope_backend.app.internal.tasks.system_tasks import ImportMetadata
+
+
+class PluginModule(Module):
+    meta = ModuleMeta(key="plugin", version=Version("1.0"))
+
+    def __init__(self, context: ModuleContext) -> None:
+        super().__init__(context)
+        self.plugins = PluginRegistry(self.registry)
+        self.plugins.add_plugin(PluginRegistry.BASE_PLUGIN_ID, BasePlugin)
+
+        if config.PLUGIN_DIR:
+            self.plugins.load_from_dir(
+                config.PLUGIN_DIR,
+                [path.name for path in config.PLUGIN_DIR.iterdir() if path.is_dir()],
+            )
+
+    def create_app(self) -> FastAPI:
+        app = FastAPI(
+            title="Plugin",
+            version=str(self.meta.version),
+            docs_url=None,
+            redoc_url=None,
+        )
+        app.state.plugin_registry = self.plugins
+
+        app.include_router(router)
+
+        return app
+
+    def import_archive(
+        self,
+        session: "Session",
+        archive: zipfile.ZipFile,
+        metadata: "ImportMetadata",
+    ) -> list[SSEMessage] | None:
+        if not is_plugin_archive(archive):
+            return None
+
+        return import_plugin_archive(self.plugins, archive, metadata["fileName"])

ocelescope_module_plugin/ocel_visualization.py

@@ -0,0 +1,68 @@
+"""Plotly summary of an OCEL, mirroring the bar lists the frontend renders."""
+
+import pandas as pd
+import plotly.graph_objects as go
+from plotly.subplots import make_subplots
+
+from ocelescope import OCEL, Plotly
+
+DEFAULT_TOP_N = 8
+
+_ACTIVITY_COLOR = "#228be6"
+_OBJECT_COLOR = "#12b886"
+
+
+def _bars(counts: pd.Series, color: str) -> go.Bar:
+    """Horizontal bars, most frequent on top."""
+    ordered = counts.iloc[::-1]
+    values = [int(value) for value in ordered]
+
+    return go.Bar(
+        x=values,
+        y=[str(label) for label in ordered.index],
+        orientation="h",
+        marker_color=color,
+        text=[f"{value:,}" for value in values],
+        textposition="outside",
+        cliponaxis=False,
+        hovertemplate="%{y}: %{x:,}<extra></extra>",
+    )
+
+
+def _title(label: str, counts: pd.Series, top_n: int) -> str:
+    total = len(counts)
+    return (
+        f"{label} (top {top_n} of {total:,})"
+        if total > top_n
+        else f"{label} ({total:,})"
+    )
+
+
+def visualize_ocel(ocel: OCEL, top_n: int = DEFAULT_TOP_N) -> Plotly:
+    """Chart the activity and object type frequencies of an OCEL."""
+    activity_counts = ocel.events.activity_counts
+    object_counts = ocel.objects.counts
+
+    figure = make_subplots(
+        rows=2,
+        cols=1,
+        subplot_titles=(
+            _title("Activity", activity_counts, top_n),
+            _title("Object type", object_counts, top_n),
+        ),
+        vertical_spacing=0.15,
+    )
+    figure.add_trace(_bars(activity_counts.head(top_n), _ACTIVITY_COLOR), row=1, col=1)
+    figure.add_trace(_bars(object_counts.head(top_n), _OBJECT_COLOR), row=2, col=1)
+
+    figure.update_xaxes(visible=False)
+    figure.update_yaxes(automargin=True, ticksuffix="  ")
+    figure.update_layout(
+        showlegend=False,
+        bargap=0.35,
+        margin={"l": 8, "r": 32, "t": 32, "b": 8},
+        paper_bgcolor="rgba(0,0,0,0)",
+        plot_bgcolor="rgba(0,0,0,0)",
+    )
+
+    return Plotly(figure)