Plugin Environment

Ocelescope plugins run in a fixed Python environment provided by the Ocelescope runtime.
Plugins can only rely on packages that are available in the Ocelescope environment.

If you need a package that is not available in the plugin environment, please open a package request on GitHub.

Installing the plugin extra

Ocelescope exposes an optional dependency group for plugin-related packages.
You can install it with:

pip install "ocelescope[plugin]"

This is the recommended way to install packages that are intended to be available in the shared plugin environment.

What the plugin environment contains

The runtime is Python 3.13. Beyond the ocelescope package itself, the following third-party packages are available to every plugin. They come in through the ocelescope package and its plugin extra, so installing ocelescope[plugin] locally gives you the same set.

Always available (dependencies of ocelescope):

Package	Version
`duckdb`	`>=1.5.4`
`graphviz`	`>=0.21`
`ijson`	`>=3.5.0`
`lxml`	`>=6.1.1`
`matplotlib`	`>=3.10.9`
`orjson`	`>=3.11.7`
`pandas`	`>=2.3.1`
`plotly`	`>=6.3.1`
`pm4py`	`~=2.7.23`
`polars`	`>=1.40.1`
`pyarrow`	`>=24.0.0`
`pydantic`	`>=2.11.7`
`r4pm`	`>=0.6.0`

Added by the plugin extra:

Package	Version
`more-itertools`	`>=11.1.0`
`networkx`	`>=3.5`
`numpy`	`>=2.3.2`
`pulp`	`>=3.3.2`
`scikit-learn`	`>=1.9.0`

These are the version constraints declared by the ocelescope package (currently 0.6.0); the exact version installed in the runtime may be newer within each constraint.

Bundling wheel files inside a plugin

If your plugin needs a dependency that is not available in the shared plugin environment, you can bundle wheel files directly inside the plugin.

This is especially useful for compiled packages such as Rust bindings.

Store the wheels inside a wheels/ folder in your plugin package:

my-plugin/
├── src/
│   └── my_plugin/
│       ├── __init__.py
│       ├── plugin.py
│       └── wheels/
│           ├── some_package-1.0.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
│           └── some_package-1.0.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
└── pyproject.toml

After building, the plugin ZIP should look like this:

MyPlugin.zip/
└── my_plugin/
    ├── __init__.py
    ├── plugin.py
    └── wheels/
        ├── some_package-1.0.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
        └── some_package-1.0.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Build wheels that are compatible with Python 3.13.
If you want to support both amd64 and arm64, include one wheel for each platform.