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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,273 @@
1
+ import importlib.util
2
+ import shutil
3
+ import sys
4
+ from collections.abc import Generator
5
+ from contextlib import ExitStack, contextmanager
6
+ from copy import deepcopy
7
+ from pathlib import Path
8
+ from types import ModuleType
9
+ from typing import TYPE_CHECKING, Any
10
+
11
+ from ocelescope.plugin.decorators import PluginIO
12
+ from ocelescope_backend.app.internal.exceptions import BadRequest
13
+ from ocelescope_backend.app.internal.registry.resource import RegistryError
14
+
15
+ from ocelescope import OCEL, Plugin, PluginMethod, ResourceBase
16
+ from ocelescope_module_plugin.dynamic_import import (
17
+ import_wheel_dynamically,
18
+ is_wheel_compatible,
19
+ )
20
+ from ocelescope_module_plugin.models.plugin import PluginApi
21
+
22
+ if TYPE_CHECKING:
23
+ from ocelescope_backend.app.internal.session import Session
24
+ from ocelescope_backend.app.modules.context import ModuleRegistry
25
+
26
+
27
+ class PluginNotFound(RegistryError):
28
+ """Raised when no plugin could be found for a lookup.
29
+
30
+ Attributes:
31
+ plugin_id: The registry id or module name the plugin was looked for in.
32
+ """
33
+
34
+ def __init__(self, plugin_id: str):
35
+ self.plugin_id = plugin_id
36
+ super().__init__(f"No plugin found for {plugin_id!r}")
37
+
38
+
39
+ class MethodNotFound(RegistryError):
40
+ """Raised when a plugin has no method under the requested name.
41
+
42
+ Attributes:
43
+ plugin_id: The registry id of the plugin that was looked in.
44
+ method_name: The method name that was looked for.
45
+ """
46
+
47
+ def __init__(self, plugin_id: str, method_name: str):
48
+ self.plugin_id = plugin_id
49
+ self.method_name = method_name
50
+ super().__init__(f"Plugin {plugin_id!r} has no method {method_name!r}")
51
+
52
+
53
+ class PluginAlreadyRegistered(RegistryError):
54
+ """Raised when a plugin with the same name and version is already registered.
55
+
56
+ Attributes:
57
+ name: The name of the plugin that collided.
58
+ version: The version of the plugin that collided.
59
+ """
60
+
61
+ def __init__(self, name: str, version: str):
62
+ self.name = name
63
+ self.version = version
64
+ super().__init__(
65
+ f"Plugin {name!r} with version {version!r} is already registered"
66
+ )
67
+
68
+
69
+ def find_plugin_class(module: ModuleType) -> type[Plugin]:
70
+ plugin_class = next(
71
+ (
72
+ var
73
+ for var in vars(module).values()
74
+ if isinstance(var, type) and issubclass(var, Plugin) and var is not Plugin
75
+ ),
76
+ None,
77
+ )
78
+
79
+ if plugin_class is None:
80
+ raise PluginNotFound(module.__name__)
81
+
82
+ return plugin_class
83
+
84
+
85
+ class PluginRegistry:
86
+ BASE_PLUGIN_ID: str = "__BASE_PLUGIN_ID__"
87
+
88
+ def __init__(self, module_registry: "ModuleRegistry"):
89
+ self._registry: dict[str, Plugin] = {}
90
+ self._module_registry = module_registry
91
+
92
+ def add_plugin(self, id: str, plugin_class: type[Plugin]) -> Plugin:
93
+ if any(
94
+ plugin_class.get_name() == existing_plugin.get_name()
95
+ and plugin_class.version == existing_plugin.version
96
+ for existing_plugin in self._registry.values()
97
+ ):
98
+ raise PluginAlreadyRegistered(
99
+ name=plugin_class.get_name(), version=plugin_class.version
100
+ )
101
+
102
+ self._registry[id] = plugin_class()
103
+ self._module_registry.load(plugin_class.get_resources(), namespace=id)
104
+
105
+ return self._registry[id]
106
+
107
+ def load_from_dir(
108
+ self, plugin_dir: Path, plugin_ids: list[str], ignore_errors: bool = True
109
+ ) -> list[str]:
110
+ loaded_plugins = []
111
+
112
+ for id in plugin_ids:
113
+ module_path = plugin_dir / id
114
+ if not (module_path / "__init__.py").exists():
115
+ shutil.rmtree(module_path, ignore_errors=True)
116
+ continue
117
+
118
+ if id in sys.modules:
119
+ continue
120
+
121
+ # TODO: Put wheels folder into config
122
+ if (module_path / "wheels").exists():
123
+ compatible_wheels = [
124
+ wheel_file
125
+ for wheel_file in (module_path / "wheels").iterdir()
126
+ if wheel_file.suffix == ".whl"
127
+ and is_wheel_compatible(wheel_file.name)
128
+ ]
129
+
130
+ for wheel in compatible_wheels:
131
+ import_wheel_dynamically(wheel)
132
+
133
+ spec = importlib.util.spec_from_file_location(
134
+ id, module_path / "__init__.py"
135
+ )
136
+
137
+ try:
138
+ if spec and spec.loader:
139
+ module = importlib.util.module_from_spec(spec)
140
+ sys.modules[id] = module
141
+ spec.loader.exec_module(module)
142
+ try:
143
+ self.add_plugin(id, find_plugin_class(module))
144
+ loaded_plugins.append(id)
145
+ except Exception:
146
+ self.unload_module(id)
147
+ raise
148
+ else:
149
+ raise ImportError(f"Could not create module spec for plugin {id!r}")
150
+ except Exception:
151
+ shutil.rmtree(module_path, ignore_errors=True)
152
+
153
+ if not ignore_errors:
154
+ raise
155
+
156
+ return loaded_plugins
157
+
158
+ def list_plugins(self) -> list[PluginApi]:
159
+ return [
160
+ PluginApi.from_plugin(id, plugin) for id, plugin in self._registry.items()
161
+ ]
162
+
163
+ def get_plugin(self, id: str) -> Plugin | None:
164
+ return self._registry.get(id)
165
+
166
+ def get_method(self, plugin_id: str, method_name: str) -> PluginMethod:
167
+ plugin = self.get_plugin(plugin_id)
168
+ if plugin is None:
169
+ raise PluginNotFound(plugin_id)
170
+
171
+ method = plugin.method_map().get(method_name)
172
+
173
+ if method is None:
174
+ raise MethodNotFound(plugin_id, method_name)
175
+
176
+ return method
177
+
178
+ def _resolve_plugin_input(
179
+ self,
180
+ session: "Session",
181
+ io: PluginIO,
182
+ input_resources: dict[str, str | None],
183
+ input_stack: ExitStack | None = None,
184
+ ) -> ResourceBase | OCEL | None:
185
+ id = input_resources.get(io.name, None)
186
+
187
+ if not id:
188
+ return
189
+
190
+ if io.io_type == "ocel":
191
+ ocel = session.get_ocel(id).open()
192
+
193
+ if input_stack is not None:
194
+ return input_stack.enter_context(ocel)
195
+
196
+ with ocel:
197
+ return deepcopy(ocel)
198
+
199
+ schema_hash = session.get_resource(id).schema_hash
200
+ resource_class = next(
201
+ (t for t in io.resource_types if t.get_schema_hash() == schema_hash), None
202
+ )
203
+
204
+ if resource_class is None:
205
+ raise BadRequest(
206
+ f"Resource {id} cannot be passed as {io.name!r}: expected "
207
+ + " or ".join(t.__name__ for t in io.resource_types)
208
+ )
209
+
210
+ if input_stack is not None:
211
+ return input_stack.enter_context(session.open_resource(id, resource_class))
212
+
213
+ return session.load_resource(id, resource_class)
214
+
215
+ def get_plugin_kwargs(
216
+ self,
217
+ session: "Session",
218
+ plugin_id: str,
219
+ method_name: str,
220
+ input_resources: dict[str, str | None],
221
+ require_inputs: bool = True,
222
+ input_stack: ExitStack | None = None,
223
+ ) -> dict[str, Any]:
224
+
225
+ method = self.get_method(plugin_id, method_name)
226
+
227
+ kwargs: dict[str, Any] = {
228
+ io.name: self._resolve_plugin_input(
229
+ session, io, input_resources, input_stack
230
+ )
231
+ for io in method.inputs
232
+ }
233
+
234
+ if require_inputs:
235
+ missing = [
236
+ io.name
237
+ for io in method.inputs
238
+ if not io.is_optional and kwargs[io.name] is None
239
+ ]
240
+
241
+ if missing:
242
+ raise ValueError(f"Missing required input: {', '.join(missing)}")
243
+
244
+ return kwargs
245
+
246
+ @contextmanager
247
+ def computed_kwargs(
248
+ self,
249
+ session: "Session",
250
+ plugin_id: str,
251
+ method_name: str,
252
+ input_resources: dict[str, str | None],
253
+ ) -> Generator[dict[str, Any]]:
254
+ """Kwargs for a computed-value provider, valid for the block.
255
+
256
+ A provider only reads, so its OCELs and resources are read-only views
257
+ rather than in-memory copies -- they are closed when the block
258
+ exits and must not outlive it. Inputs are not required to be filled in
259
+ yet either: the form the provider computes a field for is still open.
260
+ """
261
+ with ExitStack() as input_stack:
262
+ yield self.get_plugin_kwargs(
263
+ session=session,
264
+ plugin_id=plugin_id,
265
+ method_name=method_name,
266
+ input_resources=input_resources,
267
+ require_inputs=False,
268
+ input_stack=input_stack,
269
+ )
270
+
271
+ def unload_module(self, id: str):
272
+ self._registry.pop(id, None)
273
+ self._module_registry.unload(namespace=id)
@@ -0,0 +1,21 @@
1
+ from fastapi.exceptions import HTTPException
2
+ from ocelescope_backend.app.internal.tasks.base import TaskState
3
+
4
+ from ocelescope_module_plugin.models.plugin_result import PluginOutput
5
+ from ocelescope_module_plugin.tasks import PluginTask
6
+
7
+
8
+ def select_outputs(plugin_task: PluginTask, ids: list[str]) -> list[PluginOutput]:
9
+ """Resolve the requested output ids, rejecting any the task did not produce."""
10
+ if plugin_task.state != TaskState.SUCCESS:
11
+ raise HTTPException(status_code=409, detail="Task has no results yet")
12
+
13
+ outputs = {output.id: output for output in PluginOutput.from_task(plugin_task)}
14
+
15
+ selected: list[PluginOutput] = []
16
+ for id in ids:
17
+ if id not in outputs:
18
+ raise HTTPException(status_code=404, detail=f"Output {id} does not exist")
19
+ selected.append(outputs[id])
20
+
21
+ return selected
@@ -0,0 +1,258 @@
1
+ import shutil
2
+ import zipfile
3
+ from datetime import UTC, datetime
4
+ from tempfile import NamedTemporaryFile
5
+ from typing import Annotated, Any
6
+
7
+ from fastapi import Body
8
+ from fastapi.exceptions import HTTPException
9
+ from fastapi.routing import APIRouter
10
+ from ocelescope.ocel.io import export_duckdb_ocel
11
+ from ocelescope_backend.app.dependencies import ApiOcel, ApiSession
12
+ from ocelescope_backend.app.internal.exceptions import NotFound
13
+ from ocelescope_backend.app.internal.model.response import TempFileResponse
14
+ from ocelescope_backend.app.internal.registry.resource import RegistryError
15
+ from ocelescope_backend.app.internal.tasks.base import (
16
+ TaskState,
17
+ call_with_known_params,
18
+ )
19
+ from ocelescope_backend.app.sse_manager import (
20
+ InvalidationRequest,
21
+ sse_manager,
22
+ )
23
+ from pydantic import BaseModel
24
+
25
+ from ocelescope import Plotly
26
+ from ocelescope_module_plugin.config import config
27
+ from ocelescope_module_plugin.dependencies import ApiPluginRegistry, ApiPluginTask
28
+ from ocelescope_module_plugin.models.plugin import MethodApi, PluginApi
29
+ from ocelescope_module_plugin.models.plugin_result import (
30
+ PluginOutput,
31
+ ResultSelection,
32
+ )
33
+ from ocelescope_module_plugin.ocel_visualization import visualize_ocel
34
+ from ocelescope_module_plugin.registry import PluginRegistry
35
+ from ocelescope_module_plugin.results import select_outputs
36
+ from ocelescope_module_plugin.tasks import PluginTask
37
+
38
+ router = APIRouter(tags=["plugins"])
39
+
40
+
41
+ @router.get("/plugins", operation_id="plugins")
42
+ def get_plugins(
43
+ registry: ApiPluginRegistry, include_base: bool = False
44
+ ) -> list[PluginApi]:
45
+ return [
46
+ plugin
47
+ for plugin in registry.list_plugins()
48
+ if include_base or plugin.id != PluginRegistry.BASE_PLUGIN_ID
49
+ ]
50
+
51
+
52
+ @router.get("/plugin/{plugin_id}", operation_id="getPlugin")
53
+ def get_plugin(registry: ApiPluginRegistry, plugin_id: str) -> PluginApi | None:
54
+ plugin = registry.get_plugin(plugin_id)
55
+
56
+ if not plugin:
57
+ raise NotFound(f"No plugin found for {plugin_id!r}")
58
+
59
+ return PluginApi.from_plugin(plugin_id, plugin)
60
+
61
+
62
+ @router.get("/plugin/{plugin_id}/{method_name}", operation_id="getPluginMethod")
63
+ def get_plugin_method(
64
+ registry: ApiPluginRegistry, plugin_id: str, method_name: str
65
+ ) -> MethodApi | None:
66
+ try:
67
+ return MethodApi.from_method_meta(registry.get_method(plugin_id, method_name))
68
+ except Exception:
69
+ pass
70
+
71
+
72
+ @router.post("/plugin/{plugin_id}/{method_name}", operation_id="runPlugin")
73
+ def run_plugin(
74
+ input_resources: dict[str, str | None],
75
+ session: ApiSession,
76
+ registry: ApiPluginRegistry,
77
+ plugin_id: str,
78
+ method_name: str,
79
+ input: dict[str, Any] | None = None,
80
+ ) -> str:
81
+ try:
82
+ return PluginTask.create_plugin_task(
83
+ session,
84
+ registry,
85
+ plugin_id=plugin_id,
86
+ method_name=method_name,
87
+ input={"input": input or {}, "input_resources": input_resources},
88
+ )
89
+ except RegistryError as error:
90
+ raise NotFound(str(error))
91
+
92
+
93
+ @router.get("/task/{task_id}", operation_id="PluginResult")
94
+ def get_plugin_result(
95
+ plugin_task: ApiPluginTask,
96
+ ) -> list[PluginOutput] | None:
97
+ if plugin_task.state in (TaskState.PENDING, TaskState.STARTED):
98
+ return None
99
+
100
+ return PluginOutput.from_task(plugin_task)
101
+
102
+
103
+ @router.get("/ocel/{ocel_id}/visualization", operation_id="ocelVisualization")
104
+ def get_ocel_visualization(ocel: ApiOcel) -> Plotly:
105
+ return visualize_ocel(ocel)
106
+
107
+
108
+ class SavedResults(BaseModel):
109
+ ocel_ids: list[str]
110
+ resource_ids: list[str]
111
+
112
+
113
+ @router.post(
114
+ "/task/{task_id}/save",
115
+ operation_id="savePluginResults",
116
+ )
117
+ def save_plugin_results(
118
+ session: ApiSession,
119
+ plugin_task: ApiPluginTask,
120
+ selection: list[ResultSelection],
121
+ ) -> SavedResults:
122
+ """Save the selected results into the session as OCELs / resources."""
123
+ selected = select_outputs(plugin_task, [result.id for result in selection])
124
+
125
+ saved = SavedResults(ocel_ids=[], resource_ids=[])
126
+
127
+ for result, output in zip(selection, selected, strict=True):
128
+ name = result.name or output.name
129
+
130
+ if output.type == "ocel":
131
+ saved.ocel_ids.append(
132
+ session.add_ocel(
133
+ session.get_ocel(output.id).db_path,
134
+ name,
135
+ source_id=plugin_task.plugin_id,
136
+ )
137
+ )
138
+ else:
139
+ saved.resource_ids.append(
140
+ session.add_resource(
141
+ session.get_resource(output.id),
142
+ name=name,
143
+ source_id=plugin_task.plugin_id,
144
+ )
145
+ )
146
+
147
+ return saved
148
+
149
+
150
+ @router.post(
151
+ "/task/{task_id}/download",
152
+ operation_id="downloadPluginResults",
153
+ )
154
+ def download_plugin_results(
155
+ plugin_task: ApiPluginTask,
156
+ ids: Annotated[list[str], Body(embed=True)],
157
+ ) -> TempFileResponse:
158
+ """Bundle the selected results into a zip for download."""
159
+ selected = select_outputs(plugin_task, ids)
160
+
161
+ archive_name = f"{plugin_task.plugin_id}_{plugin_task.method_name}_results"
162
+ file_response = TempFileResponse(
163
+ prefix=datetime.now(tz=UTC).strftime("%Y%m%d-%H%M%S") + "-",
164
+ suffix=".zip",
165
+ filename=f"{archive_name}.zip",
166
+ )
167
+
168
+ used_names: set[str] = set()
169
+
170
+ def _unique(name: str, extension: str) -> str:
171
+ filename = f"{name}{extension}"
172
+ suffix = 1
173
+ while filename in used_names:
174
+ filename = f"{name}_{suffix}{extension}"
175
+ suffix += 1
176
+ used_names.add(filename)
177
+ return filename
178
+
179
+ with zipfile.ZipFile(file_response.tmp_path, "w", zipfile.ZIP_DEFLATED) as archive:
180
+ for output in selected:
181
+ if output.type == "ocel":
182
+ db_path = plugin_task.session.get_ocel(output.id).db_path
183
+ with NamedTemporaryFile(suffix=".json") as ocel_file:
184
+ export_duckdb_ocel(db_path, ocel_file.name)
185
+ archive.write(ocel_file.name, arcname=_unique(output.name, ".json"))
186
+ else:
187
+ with (
188
+ NamedTemporaryFile(suffix=".ocelescope") as resource_file,
189
+ plugin_task.session.open_resource(output.id) as resource,
190
+ ):
191
+ resource.write(resource_file.name)
192
+ archive.write(
193
+ resource_file.name,
194
+ arcname=_unique(output.name, ".ocelescope"),
195
+ )
196
+
197
+ return file_response
198
+
199
+
200
+ @router.post(
201
+ "/plugin/{plugin_id}/{method_name}/computed/{provider}",
202
+ operation_id="getComputedValues",
203
+ )
204
+ def get_computed(
205
+ input_resources: dict[str, str | None],
206
+ configuration_input: dict[str, Any],
207
+ session: ApiSession,
208
+ registry: ApiPluginRegistry,
209
+ plugin_id: str,
210
+ provider: str,
211
+ method_name: str,
212
+ ) -> list[str]:
213
+ try:
214
+ method = registry.get_method(plugin_id, method_name)
215
+ except RegistryError as error:
216
+ raise NotFound(str(error))
217
+
218
+ input_class = method.configuration_input
219
+ fn = getattr(input_class, provider, None)
220
+ if fn is None:
221
+ raise NotFound(f"{method_name}.{provider} not found")
222
+
223
+ try:
224
+ with registry.computed_kwargs(
225
+ session=session,
226
+ plugin_id=plugin_id,
227
+ method_name=method_name,
228
+ input_resources=input_resources,
229
+ ) as kwargs:
230
+ kwargs["input"] = configuration_input
231
+
232
+ return call_with_known_params(fn, **kwargs)
233
+ except Exception:
234
+ return []
235
+
236
+
237
+ @router.delete("/plugin/{plugin_id}", operation_id="deletePlugin")
238
+ def delete_plugin(registry: ApiPluginRegistry, plugin_id: str, session: ApiSession):
239
+ if not config.PLUGIN_DIR:
240
+ raise HTTPException(status_code=404, detail="Plugin files not found")
241
+
242
+ plugin_path = config.PLUGIN_DIR / plugin_id
243
+
244
+ if not plugin_path.exists():
245
+ raise HTTPException(status_code=404, detail="Plugin files not found")
246
+
247
+ registry.unload_module(plugin_id)
248
+
249
+ shutil.rmtree(plugin_path, ignore_errors=True)
250
+
251
+ sse_manager.send_safe(
252
+ session.id,
253
+ InvalidationRequest(
254
+ routes=["plugins", "discoveryMethods"],
255
+ ),
256
+ )
257
+
258
+ return {"status": "deleted", "module": plugin_id}