ocelescope-module-ocel 0.1.0__tar.gz

ocelescope_module_ocel-0.1.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.3
+Name: ocelescope-module-ocel
+Version: 0.1.0
+Summary: Ocelescope backend module exposing OCEL inspection routes
+Requires-Dist: fastapi>=0.136.0
+Requires-Dist: ocelescope>=0.4.0,<0.5.0
+Requires-Dist: ocelescope-backend>=0.2.0,<0.3.0
+Requires-Dist: polars>=1.40
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# ocelescope-module-ocel
+
+Ocelescope backend module exposing the OCEL inspection API (metadata, attributes,
+object/event summaries, relation counts, variants, quantities and export).
+
+Mounted at `/modules/ocel/v1`.

ocelescope_module_ocel-0.1.0/README.md

@@ -0,0 +1,6 @@
+# ocelescope-module-ocel
+
+Ocelescope backend module exposing the OCEL inspection API (metadata, attributes,
+object/event summaries, relation counts, variants, quantities and export).
+
+Mounted at `/modules/ocel/v1`.

ocelescope_module_ocel-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "ocelescope-module-ocel"
+version = "0.1.0"
+description = "Ocelescope backend module exposing OCEL inspection routes"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+  "fastapi>=0.136.0",
+  "ocelescope>=0.4.0,<0.5.0",
+  "ocelescope-backend>=0.2.0,<0.3.0",
+  "polars>=1.40",
+]
+
+[project.entry-points."ocelescope_backend.modules"]
+ocelV1 = "ocelescope_module_ocel.module:Ocel"
+
+
+[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 = { workspace = true }

ocelescope_module_ocel-0.1.0/src/ocelescope_module_ocel/models/__init__.py

@@ -0,0 +1,30 @@
+from ocelescope_module_ocel.models.attributes import (
+    AggregatedAttribute,
+    Attribute,
+    TypedAttribute,
+)
+from ocelescope_module_ocel.models.metadata import OcelMetadata
+from ocelescope_module_ocel.models.quantities import QuantityInfo
+from ocelescope_module_ocel.models.relations import (
+    RelationCombination,
+    RelationCountSummary,
+)
+from ocelescope_module_ocel.models.time import (
+    Date_Distribution_Item,
+    Entity_Time_Info,
+)
+from ocelescope_module_ocel.models.variants import ObjectTypeVariants, ObjectVariant
+
+__all__ = [
+    "AggregatedAttribute",
+    "Attribute",
+    "TypedAttribute",
+    "OcelMetadata",
+    "QuantityInfo",
+    "RelationCombination",
+    "RelationCountSummary",
+    "Date_Distribution_Item",
+    "Entity_Time_Info",
+    "ObjectTypeVariants",
+    "ObjectVariant",
+]

ocelescope_module_ocel-0.1.0/src/ocelescope_module_ocel/models/attributes.py

@@ -0,0 +1,32 @@
+from enum import StrEnum
+
+from pydantic import BaseModel
+
+
+class ValueType(StrEnum):
+    EMPTY = "empty"
+    STRING = "string"
+    BOOL = "bool"
+    INT = "int"
+    FLOAT = "float"
+    DATE = "date"
+
+
+class Attribute(BaseModel):
+    name: str
+    min: str | int | float
+    max: str | int | float
+    distinct_values: int
+    type: ValueType
+
+
+class AggregatedAttribute(Attribute):
+    """An attribute summarized across every entity type that carries it."""
+
+    entity_type_names: list[str]
+
+
+class TypedAttribute(Attribute):
+    """An attribute summarized for a single entity type (activity / object type)."""
+
+    entity_type: str

ocelescope_module_ocel-0.1.0/src/ocelescope_module_ocel/models/metadata.py

@@ -0,0 +1,31 @@
+from typing import TYPE_CHECKING
+
+from ocelescope_backend.app.internal.registry import registry_manager
+from ocelescope_backend.app.internal.registry.extension import OCELExtensionDescription
+from pydantic import BaseModel
+
+if TYPE_CHECKING:
+    from ocelescope_backend.app.internal.model.ocel import SessionOCEL
+
+
+class OcelMetadata(BaseModel):
+    id: str
+    name: str
+    created_at: str
+    extensions: list[OCELExtensionDescription]
+    filter_applied: bool | None
+
+    @classmethod
+    def from_handle(cls, handle: "SessionOCEL", filter_applied: bool | None = None):
+        descriptions = registry_manager.get_extension_descriptions()
+        return cls(
+            id=handle.id,
+            created_at=handle.created_at,
+            name=handle.name,
+            extensions=[
+                descriptions[extension.__class__.__name__]
+                for extension in handle.extensions
+                if extension.__class__.__name__ in descriptions
+            ],
+            filter_applied=filter_applied,
+        )

ocelescope_module_ocel-0.1.0/src/ocelescope_module_ocel/models/quantities.py

@@ -0,0 +1,22 @@
+from typing import Self
+
+from ocelescope import OCEL
+from pydantic import BaseModel
+
+
+class QuantityInfo(BaseModel):
+    item_types: list[str]
+    total_object_count: int
+    total_event_count: int
+    object_types: list[str]
+    activities: list[str]
+
+    @classmethod
+    def from_ocel(cls, ocel: OCEL) -> Self:
+        return cls(
+            item_types=ocel.quantities.item_types,
+            total_object_count=len(ocel.quantities.objects),
+            total_event_count=len(ocel.quantities.events),
+            object_types=ocel.quantities.object_types,
+            activities=ocel.quantities.activities,
+        )

ocelescope_module_ocel-0.1.0/src/ocelescope_module_ocel/models/relations.py

@@ -0,0 +1,42 @@
+from pydantic import BaseModel
+
+
+class RelationCombination(BaseModel):
+    """A distinct (source, target, qualifier) combination of a relation.
+
+    Attributes:
+        source: The source object or event type.
+        target: The target object or event type.
+        qualifier: The relation qualifier (empty string when none applies).
+    """
+
+    source: str
+    target: str
+    qualifier: str
+
+
+class RelationCountSummary(BaseModel):
+    """Summary statistics for relationship multiplicities in O2O or E2O relations.
+
+    For each (source type, target type[, qualifier]) combination, captures how many
+    related items occur per source instance.
+
+    Attributes:
+        qualifier: The relation qualifier (empty string when none applies).
+        qualifiers: The qualifiers aggregated under a (source, target) pair. For
+            aggregated rows (``with_qualifier=False``) this lists every qualifier;
+            for per-qualifier rows it is the single-element list ``[qualifier]``.
+        source: The source object or event type.
+        target: The target object or event type.
+        min_count: The minimum number of related items for any source instance.
+        max_count: The maximum number of related items for any source instance.
+        sum: The total number of relation occurrences across all instances.
+    """
+
+    qualifier: str
+    qualifiers: list[str] = []
+    source: str
+    target: str
+    min_count: int
+    max_count: int
+    sum: int

ocelescope_module_ocel-0.1.0/src/ocelescope_module_ocel/models/time.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]

ocelescope_module_ocel-0.1.0/src/ocelescope_module_ocel/models/variants.py

@@ -0,0 +1,33 @@
+from pydantic import BaseModel
+
+
+class ObjectVariant(BaseModel):
+    """A single object variant: a distinct activity sequence objects of a type follow.
+
+    Attributes:
+        variant_id: Identifier of the variant
+            (``<object_type>_<hash of the activity sequence>``). It depends only
+            on the sequence, so it stays the same across filtered views of a log.
+        activities: The ordered activity sequence that defines the variant.
+        event_count: Number of events in the variant (length of ``activities``).
+        case_count: Number of objects (cases) that follow this variant.
+    """
+
+    variant_id: str
+    activities: list[str]
+    event_count: int
+    case_count: int
+
+
+class ObjectTypeVariants(BaseModel):
+    """All variants of a single object type together with the totals across them.
+
+    Attributes:
+        variants: The distinct variants, sorted by frequency (descending).
+        case_count: Total number of cases (objects) of the object type.
+        event_count: Total number of events across all cases of the object type.
+    """
+
+    variants: list[ObjectVariant]
+    case_count: int
+    event_count: int

ocelescope_module_ocel-0.1.0/src/ocelescope_module_ocel/module.py

@@ -0,0 +1,19 @@
+from fastapi import FastAPI
+from ocelescope_backend.app.modules import Module, ModuleMeta
+from packaging.version import Version
+
+from ocelescope_module_ocel.routers import router
+
+
+class Ocel(Module):
+    meta = ModuleMeta(key="ocel", version=Version("1.0"))
+
+    @classmethod
+    def create_app(cls) -> FastAPI:
+        app = FastAPI(
+            title="OCEL", version=str(cls.meta.version), docs_url=None, redoc_url=None
+        )
+
+        app.include_router(router)
+
+        return app

ocelescope_module_ocel-0.1.0/src/ocelescope_module_ocel/routers/__init__.py

@@ -0,0 +1,28 @@
+"""The OCEL module's router, assembled from the per-resource sub-routers.
+
+``management`` is included first so its static single-segment paths (``/default``,
+``/extension/meta``) are matched before the ``/{ocel_id}`` catch-all.
+"""
+
+from fastapi import APIRouter
+
+from ocelescope_module_ocel.routers import (
+    attributes,
+    events,
+    export,
+    management,
+    objects,
+    quantities,
+    relations,
+)
+
+router = APIRouter()
+router.include_router(management.router)
+router.include_router(attributes.router)
+router.include_router(objects.router)
+router.include_router(events.router)
+router.include_router(relations.router)
+router.include_router(quantities.router)
+router.include_router(export.router)
+
+__all__ = ["router"]

ocelescope_module_ocel-0.1.0/src/ocelescope_module_ocel/routers/attributes.py

@@ -0,0 +1,80 @@
+"""Aggregated and per-type attribute summaries (computation in ``util.attributes``)."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Query
+from ocelescope_backend.app.dependencies import ApiOcel
+from ocelescope_backend.app.internal.model.base import PaginatedResponse
+
+from ocelescope_module_ocel.models import AggregatedAttribute, TypedAttribute
+from ocelescope_module_ocel.util import attributes as attribute_util
+from ocelescope_module_ocel.util.attributes import EntityType
+
+router = APIRouter()
+
+
+@router.get("/{ocel_id}/attributes", operation_id="AggregatedAttributes")
+def get_aggr_attributes(
+    ocel: ApiOcel,
+    page: Annotated[int, Query(ge=1)] = 1,
+    page_size: Annotated[int, Query()] = 10,
+    entity_type: Annotated[EntityType, Query()] = "events",
+    attribute_names: Annotated[list[str] | None, Query()] = None,
+    entity_names: Annotated[list[str] | None, Query()] = None,
+    drop_constant: Annotated[bool, Query()] = False,
+) -> PaginatedResponse[list[AggregatedAttribute]]:
+    names = attribute_util.attribute_names(
+        ocel, entity_type, attribute_names, entity_names, drop_constant
+    )
+    page_names = names[(page - 1) * page_size : page * page_size]
+    table = attribute_util.merged_table(ocel, entity_type, page_names, entity_names)
+
+    return PaginatedResponse(
+        page=page,
+        page_size=page_size,
+        total_items=len(names),
+        response=attribute_util.aggregate_attributes(table),
+    )
+
+
+@router.get(
+    "/{ocel_id}/objects/attributes",
+    response_model=list[TypedAttribute],
+    operation_id="objectAttributes",
+)
+def get_object_attributes(
+    ocel: ApiOcel,
+    attribute_names: Annotated[list[str], Query()] = [],
+    names: Annotated[list[str] | None, Query()] = None,
+) -> list[TypedAttribute]:
+    table = attribute_util.merged_object_table(ocel, attribute_names or None, names)
+    return attribute_util.typed_attributes(table)
+
+
+@router.get(
+    "/{ocel_id}/events/attributes",
+    response_model=list[TypedAttribute],
+    operation_id="eventAttributes",
+)
+def get_event_attributes(
+    ocel: ApiOcel,
+    attribute_names: Annotated[list[str], Query()] = [],
+    names: Annotated[list[str] | None, Query()] = None,
+) -> list[TypedAttribute]:
+    table = attribute_util.merged_event_table(ocel, attribute_names or None, names)
+    return attribute_util.typed_attributes(table)
+
+
+@router.get("/{ocel_id}/attribute/names", operation_id="AttributeNames")
+def get_attribute_names(
+    ocel: ApiOcel,
+    entity_type: Annotated[EntityType | None, Query()] = None,
+) -> list[str]:
+    names: list[str] = []
+    if entity_type != "events":
+        names += attribute_util.attribute_names(ocel, "objects")
+    if entity_type != "objects":
+        names += attribute_util.attribute_names(ocel, "events")
+    return names

ocelescope_module_ocel-0.1.0/src/ocelescope_module_ocel/routers/events.py

@@ -0,0 +1,104 @@
+"""Event-centric summaries: activities, counts, ids and the time distribution."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+
+import pandas as pd
+from fastapi import APIRouter
+from ocelescope.ocel.constants.pm4py import ACTIVITY_COL, EID_COL, TIMESTAMP_COL
+from ocelescope_backend.app.dependencies import ApiOcel
+from ocelescope_backend.app.internal.model.base import PaginatedResponse
+
+from ocelescope_module_ocel.models import Date_Distribution_Item, Entity_Time_Info
+from ocelescope_module_ocel.util.pagination import paginate_ids
+
+router = APIRouter()
+
+
+@router.get("/{ocel_id}/events/activityNames", operation_id="Activities")
+def get_activities(ocel: ApiOcel) -> list[str]:
+    return ocel.events.activities
+
+
+@router.get(
+    "/{ocel_id}/events/counts",
+    response_model=dict[str, int],
+    operation_id="eventCounts",
+)
+def get_event_counts(ocel: ApiOcel) -> dict[str, int]:
+    # Ordered most frequent first, which the response preserves.
+    return {
+        str(activity): int(count)
+        for activity, count in ocel.events.activity_counts.items()
+    }
+
+
+@router.get("/{ocel_id}/events/ids", operation_id="eventIds")
+def get_event_ids(
+    ocel: ApiOcel,
+    search: str | None = None,
+    size: int = 10,
+    page: int = 1,
+) -> PaginatedResponse[list[str]]:
+    return paginate_ids(ocel.events.table, EID_COL, search, page, size)
+
+
+@router.get(
+    "/{ocel_id}/events/time",
+    response_model=Entity_Time_Info,
+    operation_id="timeInfo",
+)
+def get_time_info(
+    ocel: ApiOcel, periods: int | None = None, freq: str | None = None
+) -> Entity_Time_Info:
+
+    span = ocel.events.table.aggregate(
+        f'min("{TIMESTAMP_COL}") AS start, max("{TIMESTAMP_COL}") AS end'
+    ).fetchone()
+    assert span is not None
+    start_time, end_time = span
+
+    bins = pd.date_range(start_time, end_time, periods=periods, freq=freq)
+    if len(bins) < 2:
+        return Entity_Time_Info(
+            start_time=start_time.isoformat(),
+            end_time=end_time.isoformat(),
+            date_distribution=[],
+        )
+    edges = [edge.to_pydatetime() for edge in bins]
+
+    rows = ocel.sql(
+        f"""
+        WITH bounds AS (SELECT ? AS edges),
+        windows AS (
+            SELECT i AS window_id, edges[i + 1] AS win_start, edges[i + 2] AS win_end
+            FROM bounds, range(0, len(edges) - 1) AS steps(i)
+        )
+        SELECT w.window_id, e."{ACTIVITY_COL}" AS activity, count(*) AS count
+        FROM events e JOIN windows w
+          ON (e."{TIMESTAMP_COL}" > w.win_start AND e."{TIMESTAMP_COL}" <= w.win_end)
+             OR (w.window_id = 0 AND e."{TIMESTAMP_COL}" = w.win_start)
+        GROUP BY w.window_id, e."{ACTIVITY_COL}"
+        """,
+        [edges],
+    ).fetchall()
+
+    counts_by_window: dict[int, dict[str, int]] = defaultdict(dict)
+    for window_id, activity, count in rows:
+        counts_by_window[window_id][activity] = int(count)
+
+    date_distribution = [
+        Date_Distribution_Item(
+            start_timestamp=edges[window_id].isoformat(),
+            end_timestamp=edges[window_id + 1].isoformat(),
+            entity_count=counts_by_window[window_id],
+        )
+        for window_id in sorted(counts_by_window)
+    ]
+
+    return Entity_Time_Info(
+        start_time=start_time.isoformat(),
+        end_time=end_time.isoformat(),
+        date_distribution=date_distribution,
+    )

ocelescope_module_ocel-0.1.0/src/ocelescope_module_ocel/routers/export.py

@@ -0,0 +1,108 @@
+"""Download the OCEL, or a flattened XES log.
+
+``downloadOCEL`` streams the log straight from the DuckDB store (no materialization).
+The two XES routes flatten a chosen object type into a per-object trace log, which
+is pm4py-only, so those do pull the tables they need into memory.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+from typing import Annotated, Literal
+
+import polars as pl
+from fastapi import APIRouter, Query
+from ocelescope.ocel import Keep
+from ocelescope.ocel.constants.misc import OCELFileExtensions
+from ocelescope.ocel.constants.pm4py import OID_COL
+from ocelescope_backend.app.dependencies import ApiOcel, ApiSession
+from ocelescope_backend.app.internal.exceptions import NotFound
+from ocelescope_backend.app.internal.model.response import TempFileResponse
+
+from ocelescope import OCEL, BaseFilter
+
+router = APIRouter()
+
+
+class _ObjectIdKeep(BaseFilter):
+    """A ModuleFilter that keeps only the given object ids (for a variant sub-log)."""
+
+    object_ids: list[str]
+
+    def keep(self, ocel: OCEL) -> Keep:
+        return Keep(objects=pl.LazyFrame({OID_COL: self.object_ids}))
+
+
+@router.get("/{ocel_id}/download", summary="Download OCEL", operation_id="downloadOCEL")
+def download_ocel(
+    session: ApiSession,
+    ocel_id: str,
+    ext: OCELFileExtensions = ".json",
+    ocel_version: Literal["original", "filtered"] | None = "filtered",
+) -> TempFileResponse:
+    if ocel_id not in session.ocels:
+        raise NotFound("OCEL not found")
+
+    name = session.ocels[ocel_id].name
+    tmp_file_prefix = datetime.now().strftime("%Y%m%d-%H%M%S") + "-" + name
+    file_response = TempFileResponse(
+        prefix=tmp_file_prefix, suffix=ext, filename=name + ext
+    )
+
+    session.export_ocel(
+        ocel_id, Path(file_response.tmp_path), use_original=ocel_version == "original"
+    )
+    return file_response
+
+
+@router.get(
+    "/{ocel_id}/download/xes",
+    summary="Download OCEL as a xes",
+    operation_id="downloadFlatLog",
+)
+def download_flat_log(
+    ocel: ApiOcel, ocel_id: str, session: ApiSession, object_type_name: str
+) -> TempFileResponse:
+    name = session.ocels[ocel_id].name
+    tmp_file_prefix = f"{datetime.now().strftime('%Y%m%d-%H%M%S')}-{name}"
+    file_response = TempFileResponse(
+        prefix=tmp_file_prefix, suffix=".xes", filename=f"{name}_{object_type_name}.xes"
+    )
+
+    ocel.write_xes(object_type_name, Path(file_response.tmp_path))
+    return file_response
+
+
+@router.get(
+    "/{ocel_id}/objects/variants/download/xes",
+    summary="Download selected object variants as a flat XES log",
+    description=(
+        "Filters the OCEL to the objects of `object_type` that follow any of the "
+        "given `variant_ids`, then flattens that sub-log by `object_type` into a "
+        "XES file (one trace per object)."
+    ),
+    operation_id="downloadVariantFlatLog",
+)
+def download_variant_flat_log(
+    ocel: ApiOcel,
+    session: ApiSession,
+    ocel_id: str,
+    object_type: str,
+    variant_ids: Annotated[list[str], Query(min_length=1)],
+) -> TempFileResponse:
+    name = session.ocels[ocel_id].name
+
+    object_ids = ocel.executions.get_variant_object_ids(object_type, variant_ids)
+
+    if not object_ids:
+        raise NotFound("No objects were found for the given variants")
+
+    tmp_file_prefix = datetime.now().strftime("%Y%m%d-%H%M%S") + "-" + name
+    file_response = TempFileResponse(
+        prefix=tmp_file_prefix, suffix=".xes", filename=f"{name}_{object_type}.xes"
+    )
+
+    with ocel.filter([_ObjectIdKeep(object_ids=object_ids)]) as variant_ocel:
+        variant_ocel.write_xes(object_type, Path(file_response.tmp_path))
+    return file_response