ocelescope-backend 0.1.0__tar.gz

ocelescope_backend-0.1.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.3
+Name: ocelescope-backend
+Version: 0.1.0
+Summary: Ocelescope backend host application
+Requires-Dist: pm4py~=2.7.22
+Requires-Dist: pandas>=2.3.1
+Requires-Dist: numpy>=2.3.2
+Requires-Dist: cachetools>=6.1.0
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: pydantic-settings>=2.2.1,<3
+Requires-Dist: fastapi[standard]>=0.136.0
+Requires-Dist: uvicorn>=0.49,<0.50
+Requires-Dist: ocelescope[plugin]>=0.1.0,<0.2.0
+Requires-Dist: orjson>=3.11.3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# ocelescope-backend
+
+The Ocelescope backend host application. It exposes the FastAPI server that
+serves OCELs, resources and modules, and provides the `ocelescope-backend`
+command-line interface.
+
+## Installation
+
+```bash
+pip install ocelescope-backend
+```
+
+## Usage
+
+Start the development server:
+
+```bash
+ocelescope-backend serve
+```
+
+Other commands (e.g. generating an OpenAPI schema for a module) are available
+via:
+
+```bash
+ocelescope-backend --help
+```
+
+## Modules
+
+The backend discovers modules through the `ocelescope_backend.modules` entry
+point group. Installing a module package (for example
+[`ocelescope-module-ocelot`](../modules/ocelescope-module-ocelot)) makes it
+available to the host automatically.
+
+## About
+
+Part of [Ocelescope](https://github.com/promi4s/ocelescope), a framework for
+working with Object-Centric Event Logs developed at the Chair of Process and
+Data Science (PADS), RWTH Aachen University.
+
+📖 Documentation: <https://www.ocelescope.org>

ocelescope_backend-0.1.0/README.md

@@ -0,0 +1,41 @@
+# ocelescope-backend
+
+The Ocelescope backend host application. It exposes the FastAPI server that
+serves OCELs, resources and modules, and provides the `ocelescope-backend`
+command-line interface.
+
+## Installation
+
+```bash
+pip install ocelescope-backend
+```
+
+## Usage
+
+Start the development server:
+
+```bash
+ocelescope-backend serve
+```
+
+Other commands (e.g. generating an OpenAPI schema for a module) are available
+via:
+
+```bash
+ocelescope-backend --help
+```
+
+## Modules
+
+The backend discovers modules through the `ocelescope_backend.modules` entry
+point group. Installing a module package (for example
+[`ocelescope-module-ocelot`](../modules/ocelescope-module-ocelot)) makes it
+available to the host automatically.
+
+## About
+
+Part of [Ocelescope](https://github.com/promi4s/ocelescope), a framework for
+working with Object-Centric Event Logs developed at the Chair of Process and
+Data Science (PADS), RWTH Aachen University.
+
+📖 Documentation: <https://www.ocelescope.org>

ocelescope_backend-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "ocelescope-backend"
+version = "0.1.0"
+description = "Ocelescope backend host application"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+  "pm4py~=2.7.22",
+  "pandas>=2.3.1",
+  "numpy>=2.3.2",
+  "cachetools>=6.1.0",
+  "pydantic>=2.11.7",
+  "pydantic-settings>=2.2.1,<3",
+  "fastapi[standard]>=0.136.0",
+  "uvicorn>=0.49,<0.50",
+  "ocelescope[plugin]>=0.1.0,<0.2.0",
+  "orjson>=3.11.3",
+]
+
+[project.scripts]
+ocelescope-backend = "ocelescope_backend.cli:app"
+
+[build-system]
+requires = ["uv_build>=0.11.20,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv]
+package = true
+
+[tool.uv.sources]
+ocelescope = { workspace = true }

ocelescope_backend-0.1.0/src/ocelescope_backend/__init__.py

@@ -0,0 +1 @@
+__all__: list[str] = []

ocelescope_backend-0.1.0/src/ocelescope_backend/app/__init__.py

@@ -0,0 +1 @@
+__all__: list[str] = []

ocelescope_backend-0.1.0/src/ocelescope_backend/app/dependencies.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from fastapi import Depends, HTTPException, Request
+
+from ocelescope import OCEL
+from ocelescope_backend.app.internal.exceptions import NotFound
+from ocelescope_backend.app.internal.session import Session
+from ocelescope_backend.app.internal.tasks.plugin import PluginTask
+
+
+def get_session(request: Request) -> Session:
+    session = getattr(request.state, "session", None)
+    if not session:
+        raise HTTPException(status_code=500, detail="Session middleware not set")
+    return session
+
+
+ApiSession = Annotated[Session, Depends(get_session)]
+
+
+def get_ocel(
+    session: ApiSession,
+    ocel_id: str | None = None,
+    ocel_version: Literal["original", "filtered"] | None = "filtered",
+):
+    # Used so the generated react queries don't required them so they can be injected from the session storage
+    if not ocel_id:
+        raise HTTPException(status_code=500, detail="Ocel id is required")
+    try:
+        return session.get_ocel(
+            ocel_id, use_original=False if ocel_version != "original" else True
+        )
+    except NotFound:
+        raise HTTPException(status_code=404, detail="OCEL not found")
+
+
+ApiOcel = Annotated[OCEL, Depends(get_ocel)]
+
+
+def get_plugin_task(
+    session: ApiSession, plugin_id: str, method_name: str, task_id: str
+) -> PluginTask:
+    plugin_task = session.get_task(task_id)
+
+    if (
+        plugin_task is None
+        or not isinstance(plugin_task, PluginTask)
+        or plugin_task.plugin_id != plugin_id
+        or plugin_task.method_name != method_name
+    ):
+        raise NotFound("Task could not be found")
+
+    return plugin_task
+
+
+ApiPluginTask = Annotated[PluginTask, Depends(get_plugin_task)]

ocelescope_backend-0.1.0/src/ocelescope_backend/app/internal/config.py

@@ -0,0 +1,45 @@
+from typing import Literal
+
+from pydantic import DirectoryPath, Field
+from pydantic_settings import BaseSettings
+
+"""
+This file contains a Config class defining all environment parameters, including types, default values and descriptions.
+.env.example (and the structure of .env) should be generated using the `export_settings_as_dotenv` util function.
+"""
+
+
+class OceanConfig(BaseSettings):
+    FRONTEND_URL: str = Field(
+        default="http://frontend:3000",
+        description="The frontend URL, relevant for CORS settings",
+    )
+
+    SESSION_ID_HEADER: str = Field(
+        default="ocelescope-session-id",
+        description="The HTTP header name containing the session ID.",
+    )
+
+    EXPOSE_ERROR_DETAILS: bool = Field(
+        default=False,
+        description="When set to True, passes details of internal errors via the API. Always set to False in production environment.",
+    )
+
+    DATA_DIR: DirectoryPath | None = Field(
+        default=None,
+        description="Path to the data directory, relative to `main.py`",
+    )
+    PLUGIN_DIR: DirectoryPath | None = Field(
+        default=None,
+        description="Path to the directory, where plugins are stored",
+    )
+
+    MODE: Literal["production", "development"] | None = Field(
+        default="development", description="The mode in which the backend is running"
+    )
+
+    class Config:
+        env_file = ".env"
+
+
+config = OceanConfig()  # type: ignore

ocelescope_backend-0.1.0/src/ocelescope_backend/app/internal/discovery/__init__.py

@@ -0,0 +1,15 @@
+from ocelescope_backend.app.internal.discovery.registry import (
+    DiscoveryMethodGroup,
+    DiscoveryMethodInfo,
+    DiscoveryRegistry,
+    discovery_registry,
+    register_discovery_methods_from_module,
+)
+
+__all__ = [
+    "DiscoveryMethodGroup",
+    "DiscoveryMethodInfo",
+    "DiscoveryRegistry",
+    "discovery_registry",
+    "register_discovery_methods_from_module",
+]

ocelescope_backend-0.1.0/src/ocelescope_backend/app/internal/discovery/bootstrap.py

@@ -0,0 +1,12 @@
+"""Register discovery methods shipped with the ocelescope SDK."""
+
+from ocelescope.discovery import algorithms
+from ocelescope_backend.app.internal.discovery.registry import (
+    register_discovery_methods_from_module,
+)
+
+
+def register_builtin_discovery_methods() -> None:
+    # The SDK's `algorithms` package re-exports each built-in @discovery_method
+    # function; scanning the package module is enough to pick them all up.
+    register_discovery_methods_from_module(algorithms)

ocelescope_backend-0.1.0/src/ocelescope_backend/app/internal/discovery/registry.py

@@ -0,0 +1,137 @@
+import inspect
+from dataclasses import dataclass
+from types import ModuleType
+from typing import Any, Callable, get_type_hints
+from uuid import uuid4
+
+from ocelescope.discovery import DiscoveryMethodMeta
+from ocelescope.ocel import OCEL
+from ocelescope.resource import Resource
+from pydantic import BaseModel, ConfigDict, create_model
+
+
+def _snake_to_camel(value: str) -> str:
+    first, *rest = value.split("_")
+    return first + "".join(part.capitalize() for part in rest)
+
+
+def _build_parameter_model(func: Callable[..., Resource]) -> type[BaseModel]:
+    """Build a pydantic model that describes the function's non-OCEL parameters."""
+    sig = inspect.signature(func)
+    hints = get_type_hints(func, include_extras=True)
+
+    fields: dict[str, tuple[Any, Any]] = {}
+    for name, param in sig.parameters.items():
+        if name in ("ocel", "self"):
+            continue
+        annotation = hints.get(name, param.annotation)
+        default = param.default if param.default is not inspect.Parameter.empty else ...
+        fields[name] = (annotation, default)
+
+    config = ConfigDict(
+        alias_generator=_snake_to_camel,
+        populate_by_name=True,
+        arbitrary_types_allowed=True,
+    )
+
+    model_name = f"{func.__name__.title().replace('_', '')}Parameters"  # ty: ignore[unresolved-attribute]
+    return create_model(model_name, __config__=config, **fields)  # type: ignore[call-overload]  # ty: ignore[no-matching-overload]
+
+
+@dataclass
+class DiscoveryMethodInfo:
+    method_id: str
+    name: str
+    description: str | None
+    func: Callable[..., Resource]
+    parameter_type: type[BaseModel]
+    resource_type: type[Resource]
+
+    def parameters_schema(self) -> dict[str, Any]:
+        return self.parameter_type.model_json_schema(by_alias=True)
+
+    def parse_parameters(self, data: dict[str, Any]) -> BaseModel:
+        return self.parameter_type.model_validate(data)
+
+    def dump_parameters(self, params: BaseModel) -> dict[str, Any]:
+        return params.model_dump(by_alias=False)
+
+    def run(self, *, ocel: OCEL, parameters: BaseModel) -> Resource:
+        return self.func(ocel=ocel, **parameters.model_dump(by_alias=False))
+
+
+class DiscoveryMethodGroup:
+    def __init__(
+        self,
+        name: str,
+        variants: list[DiscoveryMethodInfo],
+    ) -> None:
+        self.name = name
+        self.variants = variants
+
+
+class DiscoveryRegistry:
+    def __init__(self) -> None:
+        self._methods: dict[str, DiscoveryMethodInfo] = {}
+
+    def register(self, meta: DiscoveryMethodMeta) -> DiscoveryMethodInfo:
+        parameter_type = _build_parameter_model(meta.func)
+
+        for existing in self._methods.values():
+            if (
+                existing.name == meta.name
+                and existing.resource_type is meta.resource_type
+            ):
+                raise TypeError(
+                    f"Discovery method '{meta.name}' is already registered for resource "
+                    f"type '{meta.resource_type.get_type()}'."
+                )
+
+        info = DiscoveryMethodInfo(
+            method_id=str(uuid4()),
+            name=meta.name,
+            description=meta.description,
+            func=meta.func,
+            parameter_type=parameter_type,
+            resource_type=meta.resource_type,
+        )
+        self._methods[info.method_id] = info
+        return info
+
+    def unregister_by_func(self, func: Callable[..., Resource]) -> None:
+        for method_id, info in list(self._methods.items()):
+            if info.func is func:
+                del self._methods[method_id]
+
+    def get(self, method_id: str) -> DiscoveryMethodInfo:
+        info = self._methods.get(method_id)
+        if info is None:
+            raise KeyError(f"Discovery method '{method_id}' is not registered")
+        return info
+
+    def list_groups(self) -> list[DiscoveryMethodGroup]:
+        groups: dict[str, DiscoveryMethodGroup] = {}
+        for info in self._methods.values():
+            if info.name not in groups:
+                groups[info.name] = DiscoveryMethodGroup(
+                    name=info.name,
+                    variants=[info],
+                )
+            else:
+                groups[info.name].variants.append(info)
+        return list(groups.values())
+
+
+discovery_registry = DiscoveryRegistry()
+
+
+def register_discovery_methods_from_module(
+    module: ModuleType,
+) -> list[DiscoveryMethodInfo]:
+    """Scan a module for functions tagged with `__discovery_meta__` and register them."""
+    registered: list[DiscoveryMethodInfo] = []
+    for value in vars(module).values():
+        meta = getattr(value, "__discovery_meta__", None)
+        if isinstance(meta, DiscoveryMethodMeta):
+            registered.append(discovery_registry.register(meta))
+    return registered

ocelescope_backend-0.1.0/src/ocelescope_backend/app/internal/docs.py

@@ -0,0 +1,58 @@
+# Modifications to the SwaggerUI interface generated by FastAPI
+
+# Hide curl commands
+# source: https://github.com/tiangolo/fastapi/discussions/3853#discussioncomment-1388209
+
+from typing import Literal
+
+from fastapi import FastAPI
+from starlette.responses import HTMLResponse
+
+from ocelescope_backend.app.internal.config import config
+
+
+def get_rapidoc_html(
+    *,
+    openapi_url: str,
+    title: str,
+    rapidoc_js_url: str = "https://unpkg.com/rapidoc/dist/rapidoc-min.js",
+    rapidoc_favicon_url: str = "https://rapidocweb.com/images/logo.png",
+):
+    return HTMLResponse(
+        f"""
+    <!doctype html> <!-- Important: must specify -->
+    <html>
+        <head>
+            <meta charset="utf-8"> <!-- Important: rapi-doc uses utf8 characters -->
+            <script type="module" src="{rapidoc_js_url}"></script>
+            <title>{title}</title>
+            <link rel="shortcut icon" href="{rapidoc_favicon_url}">
+        </head>
+        <body>
+            <rapi-doc
+                spec-url="{openapi_url}"
+                layout="row"
+                render-style="view"
+                allow-server-selection="false"
+                show-header="false"
+                show-components="true"
+                api-key-name="{config.SESSION_ID_HEADER}"
+                api-key-location="header"
+                api-key-value="-"
+            ></rapi-doc>
+        </body>
+    </html>
+    """
+    )
+
+
+def init_custom_docs(app: FastAPI):
+    assert app.openapi_url is not None
+
+    @app.get("/docs", include_in_schema=False)
+    async def docs(ui: Literal["swaggerui", "rapidoc"] = "rapidoc", curl: bool = True):
+        if ui == "rapidoc":
+            return get_rapidoc_html(
+                openapi_url=app.openapi_url or "/",
+                title=app.title + " - rapidoc",
+            )

ocelescope_backend-0.1.0/src/ocelescope_backend/app/internal/exceptions.py

@@ -0,0 +1,42 @@
+from fastapi import HTTPException
+from starlette.status import (
+    HTTP_400_BAD_REQUEST,
+    HTTP_401_UNAUTHORIZED,
+    HTTP_402_PAYMENT_REQUIRED,
+    HTTP_403_FORBIDDEN,
+    HTTP_404_NOT_FOUND,
+    HTTP_405_METHOD_NOT_ALLOWED,
+)
+
+
+class BadRequest(HTTPException):
+    def __init__(self, detail: str | None = None):
+        super().__init__(status_code=HTTP_400_BAD_REQUEST, detail=detail)
+
+
+class Unauthorized(HTTPException):
+    def __init__(self, detail: str | None = None):
+        super().__init__(status_code=HTTP_401_UNAUTHORIZED, detail=detail)
+
+
+class PaymentRequired(HTTPException):
+    def __init__(self, detail: str | None = None):
+        super().__init__(status_code=HTTP_402_PAYMENT_REQUIRED, detail=detail)
+
+
+class Forbidden(HTTPException):
+    def __init__(self, detail: str | None = None):
+        super().__init__(status_code=HTTP_403_FORBIDDEN, detail=detail)
+
+
+class NotFound(HTTPException):
+    def __init__(self, detail: str | None = None):
+        super().__init__(status_code=HTTP_404_NOT_FOUND, detail=detail)
+
+
+class MethodNotAllowed(HTTPException):
+    def __init__(self, detail: str | None = None):
+        super().__init__(status_code=HTTP_405_METHOD_NOT_ALLOWED, detail=detail)
+
+
+# ...

ocelescope_backend-0.1.0/src/ocelescope_backend/app/internal/logger.py

@@ -0,0 +1,32 @@
+import logging
+
+import uvicorn.config
+
+
+class IgnoreOptionsRequestsFilter(logging.Filter):
+    def filter(self, record):
+        if record.args is None:
+            return True
+        ip, method, route, _, code = record.args
+        return method != "OPTIONS"
+
+
+ignore_options_request_filter = IgnoreOptionsRequestsFilter("ignore_options_requests")
+
+
+LOGGER_CONFIG = uvicorn.config.LOGGING_CONFIG
+LOGGER_CONFIG["disable_existing_loggers"] = False
+
+# logger = logging.getLogger("ocean")
+
+# # Redirect own logger to uvicorn
+# uvicorn_logger = logging.getLogger("uvicorn")
+# for handler in uvicorn_logger.handlers:
+#     logger.addHandler(handler)
+
+access_logger = logging.getLogger("uvicorn.access")
+access_logger.addFilter(ignore_options_request_filter)
+
+logger = logging.getLogger("uvicorn.error")
+# logger.setLevel(logging.INFO)
+logger.setLevel(logging.DEBUG)

ocelescope_backend-0.1.0/src/ocelescope_backend/app/internal/model/base.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel, computed_field
+
+from ..utils import custom_snake2camel
+
+
+class ApiBaseModel(BaseModel):
+    class Config:
+        alias_generator = custom_snake2camel
+        populate_by_name = True
+        arbitrary_types_allowed = True
+
+
+class RequestBody(ApiBaseModel):
+    pass
+
+
+T = TypeVar("T")
+
+
+class PaginatedResponse(BaseModel, Generic[T]):
+    response: T
+    page: int
+    page_size: int
+    total_items: int
+
+    @computed_field
+    @property
+    def total_pages(self) -> int:
+        return self.total_items // self.page_size

ocelescope_backend-0.1.0/src/ocelescope_backend/app/internal/model/discovery.py

@@ -0,0 +1,38 @@
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from ocelescope import BaseFilter
+from ocelescope_backend.app.internal.model.base import ApiBaseModel, RequestBody
+
+
+class FilterEnvelope(ApiBaseModel):
+    name: str
+    payload: dict[str, Any] = Field(default_factory=dict)
+
+
+class DiscoveryRequest(BaseModel):
+    ocel_id: str
+    method_id: str
+    name: str
+    resource_type: str
+    parameters: dict[str, Any] = Field(default_factory=dict)
+    filters: list[BaseFilter] = Field(default_factory=list)
+
+
+class CreateDiscoveryTaskBody(RequestBody):
+    method_id: str
+    parameters: dict[str, Any] = Field(default_factory=dict)
+    filters: list[FilterEnvelope] = Field(default_factory=list)
+
+
+class DiscoveryVariant(ApiBaseModel):
+    method_id: str
+    resource_type: str
+    input_schema: dict[str, Any]
+    description: str | None = None
+
+
+class DiscoveryMethodMeta(ApiBaseModel):
+    name: str
+    variants: list[DiscoveryVariant]

ocelescope_backend-0.1.0/src/ocelescope_backend/app/internal/model/events.py

@@ -0,0 +1,13 @@
+from pydantic import BaseModel
+
+
+class Date_Distribution_Item(BaseModel):
+    start_timestamp: str
+    end_timestamp: str
+    entity_count: dict[str, int]
+
+
+class Entity_Time_Info(BaseModel):
+    start_time: str
+    end_time: str
+    date_distribution: list[Date_Distribution_Item]