Ocelescope Framework

Ocelescope is not one monolithic application. It is four pieces that build on each other: a shared library that defines the core data model and building blocks, a base tool that ships a working object-centric process mining (OCPM) application out of the box, and two ways to extend that application further, plugins and modules.

The figure below shows how the four pieces relate and what each one is responsible for; the sections after it go through them one by one.

Ocelescope Library

The ocelescope Python package is the shared foundation everything else is built on. It ships two kinds of building blocks:

• The classes behind the base tool’s own OCPM functionality, most importantly the OCEL data model and its filters.
• The classes used to write plugins: Plugin and @plugin_method to declare methods, Resource to define inputs and outputs, and the visualization types used to render them.

Because a plugin can only import what the library (and its plugin extra) makes available, the library effectively specifies the environment plugins run in. If a plugin needs a package that is not part of that environment, it either has to bundle it or ask for it to be added.

• Plugin Environment: what is installed and how to bundle your own dependencies
• Request a package to be added to the shared environment
• API References: the full generated reference for every class

Ocelescope Base Tool

The base tool is the application you get before installing a single plugin. It covers three areas:

• PM functionality
  • Log management: inspecting a log and filtering it down before analysis (editing is planned).
  • Basic discovery approaches, computed out of the box.
• Plugin management: uploading new plugins and running them is built in, and the input form for every plugin method is generated automatically, no frontend work required on the plugin author’s side.
• Resource management: every OCEL and every resource, whether it came from a filter, a discovery run, or a plugin, can be imported, exported, and shared between any of these elements of the framework.

Plugins

Plugins are entirely Python. A plugin’s frontend is never hand-written, it is generated from the plugin’s code, and a single plugin can bundle multiple plugin methods. Each method works the same way: it takes inputs of the types it declares, runs its code (typically an (OC)PM approach), and returns one or more resources of the types it declares, which the base tool then knows how to visualize. Plugins are loaded by dragging a .zip onto the base tool at runtime, no rebuild required.

Consequently, every plugin method is made of three parts:

1. Input specification, declared through the library’s types (OCEL, Resource subclasses, PluginInput). A method can also require a specific OCEL extension to be present on its OCEL input, but that extension must be declared explicitly rather than assumed.
2. The (OC)PM approach itself, plain Python code with no framework requirements beyond reading its declared inputs and returning its declared outputs.
3. Output definition, as one or more Ocelescope resources. Reuse an existing built-in resource (optionally annotated with extra metadata), or define your own resource and its visualization, as long as it is JSON-serializable.

What “JSON-serializable” means

A resource is JSON-serializable when every field on it is built from plain types JSON already understands: str, int, float, bool, list, dict, None, or nested Pydantic models made of the same. Pydantic (which Resource is built on) can turn anything like that into JSON with model_dump() and rebuild it later.

What is not serializable as-is: a raw pandas.DataFrame, a networkx graph, a NumPy array, or any other object Python cannot turn into str/int/float/bool/list/dict on its own. Convert these to a plain representation first (for example, a DataFrame to list[dict], a graph to a list of nodes and edges) before putting them on a resource. A quick way to check: if json.dumps(my_object.model_dump()) from Python’s json module raises, it is not serializable yet.

Modules

Modules are the heavier extension mechanism: a full custom view with its own React frontend and its own Python backend, living in a separate repository from Ocelescope itself. Unlike plugins, a module cannot be dropped in at runtime, it has to be included before the build, becoming part of the compiled base tool. The bundled Ocelot view ships exactly this way.

Architecture

The functionality view above says what each piece does; this one shows how they are actually deployed. The base tool is two services, a frontend and a backend talking over a REST API. Modules add their own view and sub-service to those two halves at build time. Plugins are uploaded through the frontend and executed by the backend’s plugin manager at runtime.