ocelescope-module-alignments 0.1.0__tar.gz

ocelescope_module_alignments-0.1.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.3
+Name: ocelescope-module-alignments
+Version: 0.1.0
+Summary: case-centric Alignments
+Author: Uy Sa Huynh
+Requires-Dist: ocelescope-backend>=0.10.1
+Requires-Dist: ocelescope-module-filter>=0.10.1,<0.11.0
+Requires-Dist: ocelescope-module-ocel>=0.10.1,<0.11.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# ocelescope-module-case-centric-alignments
+
+An [Ocelescope](https://www.ocelescope.org) backend module that computes
+case-centric alignments for object-centric event logs.
+
+For a selected object type, the log is aligned against a Petri net resource,
+or against a model discovered with Alpha+++ if none is given.
+
+## Installation
+
+```sh
+pip install ocelescope-module-alignments
+```
+
+Install it next to `ocelescope-backend`. The module is picked up automatically
+and served under `/modules/alignments/v1`.

ocelescope_module_alignments-0.1.0/README.md

@@ -0,0 +1,16 @@
+# ocelescope-module-case-centric-alignments
+
+An [Ocelescope](https://www.ocelescope.org) backend module that computes
+case-centric alignments for object-centric event logs.
+
+For a selected object type, the log is aligned against a Petri net resource,
+or against a model discovered with Alpha+++ if none is given.
+
+## Installation
+
+```sh
+pip install ocelescope-module-alignments
+```
+
+Install it next to `ocelescope-backend`. The module is picked up automatically
+and served under `/modules/alignments/v1`.

ocelescope_module_alignments-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "ocelescope-module-alignments"
+version = "0.1.0"
+readme = "README.md"
+description = "case-centric Alignments"
+requires-python = ">=3.11"
+dependencies = [
+    "ocelescope-backend>=0.10.1",
+    "ocelescope-module-filter>=0.10.1,<0.11.0",
+    "ocelescope-module-ocel>=0.10.1,<0.11.0",
+]
+
+[[project.authors]]
+name = "Uy Sa Huynh"
+
+[project.entry-points."ocelescope_backend.modules"]
+caseCentricAlignments = "ocelescope_module_alignments.module:Alignments"
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv]
+package = true

ocelescope_module_alignments-0.1.0/pyproject.toml.orig

@@ -0,0 +1,22 @@
+[project]
+name = "ocelescope-module-alignments"
+version = "0.1.0"
+readme = "README.md"
+description = "case-centric Alignments"
+authors = [{ name = "Uy Sa Huynh" }]
+requires-python = ">=3.11"
+dependencies = [
+  "ocelescope-backend>=0.10.1",
+  "ocelescope-module-filter>=0.10.1,<0.11.0",
+  "ocelescope-module-ocel>=0.10.1,<0.11.0",
+]
+
+[project.entry-points."ocelescope_backend.modules"]
+caseCentricAlignments = "ocelescope_module_alignments.module:Alignments"
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv]
+package = true

ocelescope_module_alignments-0.1.0/src/ocelescope_module_alignments/models/alignment.py

@@ -0,0 +1,69 @@
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+from ocelescope import PetriNet
+from pydantic import BaseModel
+
+
+class VariantAlignmentResult(BaseModel):
+    activities: List[str]  # The variant's activity sequence
+    frequency: int  # How many traces follow this variant
+    result: Union[Dict[str, Any]]  # The alignment result or error for this variant
+
+
+class FitnessResult(BaseModel):
+    average_fitness: float  # Average trace fitness (across all traces)
+    log_fitness: float  # Log fitness, as the total computed fitness (summing up the costs for all traces)
+    perfectly_fitting_frac: float  # Fraction of traces that perfectly fit (i.e., have an alignment cost of `0`)
+    total_costs: int  # The total cost, summed up from all traces
+
+
+class CostFunction(BaseModel):
+    log_move_cost: int  # Default cost for a log move (log event not matched by model)
+    model_move_cost: int  # Default cost for a model move (visible transition fires without matching log event)
+    silent_move_cost: int  # Default cost for a silent/tau move
+    sync_move_cost: int  # Default cost for a synchronous move
+
+
+class AlignmentOptions(BaseModel):
+    cost_fn: CostFunction  # Cost function for alignment moves
+    max_states: Optional[Optional[int]]  # Maximum number of states to visit before aborting (per trace).
+
+
+class TransitionStat(BaseModel):
+    sync_fires: int
+    model_fires: int
+
+
+class Aggregated(BaseModel):
+    total_traces: int
+    transition_stats: Dict[str, TransitionStat]
+    log_move_counts: Dict[str, int]
+
+
+class NetPlace(BaseModel):
+    id: str
+
+
+class NetTransition(BaseModel):
+    id: str
+    label: str | None
+
+
+class NetArc(BaseModel):
+    nodes: Tuple[str, str]
+    weight: int
+
+
+class ResponseNet(BaseModel):
+    places: List[NetPlace]
+    transitions: List[NetTransition]
+    arcs: List[NetArc]
+    initial_marking: Dict[str, int]
+    final_marking: Dict[str, int]
+
+
+class AlignmentsResponse(BaseModel):
+    net: ResponseNet
+    variant_alignments: List[VariantAlignmentResult]
+    fitness: FitnessResult
+    aggregated: Aggregated

ocelescope_module_alignments-0.1.0/src/ocelescope_module_alignments/module.py

@@ -0,0 +1,14 @@
+from fastapi import FastAPI
+from ocelescope_backend.app.modules import Module, ModuleMeta
+from packaging.version import Version
+
+from ocelescope_module_alignments.routes import router
+
+
+class Alignments(Module):
+    meta = ModuleMeta(key="alignments", version=Version("1.0"))
+
+    def create_app(self) -> FastAPI:
+        app = FastAPI(title="Case-Centric Alignments", version=str(self.meta.version))
+        app.include_router(router)
+        return app

ocelescope_module_alignments-0.1.0/src/ocelescope_module_alignments/routes.py

@@ -0,0 +1,45 @@
+from typing import cast
+
+from fastapi import APIRouter, HTTPException
+from ocelescope import PetriNet
+from ocelescope_backend.app.dependencies import ApiOcel, ApiSession
+from ocelescope_backend.app.sse_manager import ErrorNotification, sse_manager
+from pydantic import BaseModel
+
+from ocelescope_module_alignments.models.alignment import AlignmentsResponse
+from ocelescope_module_alignments.utils.compute_alignments import (
+    AlignmentComputationError,
+    compute_alignments,
+)
+
+router = APIRouter()
+
+
+@router.get("/{ocel_id}/alignments", operation_id="get_alignments")
+def get_alignments(
+    ocel: ApiOcel, session: ApiSession, object_type: str, resource_id: str | None = None
+) -> AlignmentsResponse:
+    try:
+        if resource_id:
+            resource_store = cast(PetriNet, session.get_resource(resource_id))
+            petri_net = PetriNet(**resource_store.data)
+        else:
+            petri_net = None
+
+        return compute_alignments(ocel, object_type, petri_net)
+    except AlignmentComputationError as e:
+        sse_manager.send_safe(
+            session_id=session.id,
+            message=ErrorNotification(
+                type="error",
+                title="Alignment computation failed",
+                message=str(e),
+                trace=e.trace,
+            ),
+        )
+        raise HTTPException(status_code=422, detail=str(e)) from e
+
+
+@router.get("/{ocel_id}/objects/types", operation_id="objectTypes")
+def get_object_types(ocel: ApiOcel) -> list[str]:
+    return ocel.objects.types

ocelescope_module_alignments-0.1.0/src/ocelescope_module_alignments/utils/compute_alignments.py

@@ -0,0 +1,245 @@
+import traceback
+import uuid
+from typing import Dict, List, Optional, Tuple
+
+import polars
+import r4pm
+from ocelescope import OCEL, PetriNet
+from ocelescope_module_alignments.models.alignment import (
+    Aggregated,
+    AlignmentOptions,
+    AlignmentsResponse,
+    FitnessResult,
+    NetArc,
+    NetPlace,
+    NetTransition,
+    ResponseNet,
+    TransitionStat,
+    VariantAlignmentResult,
+)
+from r4pm.bindings.core.event_data.object_centric.utils.flatten import flatten_ocel_on
+from r4pm.bindings.discovery.case_centric.alphappp.full import PetriNet as R4PMPetriNet
+
+
+class AlignmentComputationError(Exception):
+    def __init__(self, message: str, trace: str | None = None):
+        super().__init__(message)
+        self.trace = trace or message
+
+
+def to_r4pm_format(petri_net: PetriNet) -> R4PMPetriNet:
+    place_ids = {p.name: str(uuid.uuid4()) for p in petri_net.places}
+    transition_ids = {t.name: str(uuid.uuid4()) for t in petri_net.transitions}
+
+    def node_id(name: str) -> str:
+        return place_ids.get(name) or transition_ids[name]
+
+    places = {pid: {"id": pid} for pid in place_ids.values()}
+
+    transitions = {
+        tid: {"id": tid, "label": t.label} for t, tid in ((t, transition_ids[t.name]) for t in petri_net.transitions)
+    }
+
+    arcs = [
+        {
+            "from_to": {
+                "type": "PlaceTransition" if arc.source in place_ids else "TransitionPlace",
+                "nodes": [node_id(arc.source), node_id(arc.target)],
+            },
+            "weight": arc.weight,
+        }
+        for arc in petri_net.arcs
+    ]
+
+    initial_marking = {place_ids[name]: count for name, count in petri_net.initial_marking.items()}
+    final_marking = {place_ids[name]: count for name, count in petri_net.final_marking.items()}
+
+    return {
+        "places": places,
+        "transitions": transitions,
+        "arcs": arcs,
+        "initial_marking": initial_marking,
+        "final_markings": [final_marking] if final_marking else [],
+    }
+
+
+def flatten(petri_net: PetriNet, object_type: str) -> PetriNet:
+    place_names = {p.name for p in petri_net.places if p.object_type == object_type}
+    places_flatten = [p for p in petri_net.places if p.name in place_names]
+
+    arcs_flatten = []
+    connected_transition_names = set()
+    for arc in petri_net.arcs:
+        source_is_place = arc.source in place_names
+        target_is_place = arc.target in place_names
+        if not (source_is_place or target_is_place):
+            continue
+        arcs_flatten.append(arc)
+        if not source_is_place:
+            connected_transition_names.add(arc.source)
+        if not target_is_place:
+            connected_transition_names.add(arc.target)
+
+    transitions_flatten = [t for t in petri_net.transitions if t.name in connected_transition_names]
+
+    initial_marking_flatten = {name: count for name, count in petri_net.initial_marking.items() if name in place_names}
+    final_marking_flatten = {name: count for name, count in petri_net.final_marking.items() if name in place_names}
+
+    return PetriNet(
+        places=places_flatten,
+        transitions=transitions_flatten,
+        arcs=arcs_flatten,
+        initial_marking=initial_marking_flatten,
+        final_marking=final_marking_flatten,
+    )
+
+
+def convert_net(petri_net: R4PMPetriNet) -> ResponseNet:
+    places = [NetPlace(id=p_id) for p_id in petri_net["places"].keys()]
+    transitions = [NetTransition(id=t_id, label=t.get("label")) for t_id, t in petri_net["transitions"].items()]
+    arcs = [
+        NetArc(
+            nodes=(arc["from_to"]["nodes"][0], arc["from_to"]["nodes"][1]),
+            weight=arc["weight"],
+        )
+        for arc in petri_net["arcs"]
+    ]
+    initial_marking = petri_net.get("initial_marking") or {}
+    final_markings = petri_net.get("final_markings") or []
+    final_marking = final_markings[0] if final_markings else {}
+
+    return ResponseNet(
+        places=places,
+        transitions=transitions,
+        arcs=arcs,
+        initial_marking=initial_marking,
+        final_marking=final_marking,
+    )
+
+
+def is_flattened(petri_net: PetriNet) -> bool:
+    object_types = set()
+    for place in petri_net.places:
+        object_types.add(place.object_type)
+        if len(object_types) > 1:
+            return False
+
+    return len(object_types) == 1
+
+
+def preprocessing(ocel: OCEL, object_type: str, petri_net: PetriNet | None) -> Tuple[str, R4PMPetriNet]:
+    config = {
+        "absolute_df_clean_thresh": 1,
+        "balance_thresh": 0.2,
+        "fitness_thresh": 0.2,
+        "log_repair_loop_df_thresh_rel": 0.2,
+        "log_repair_skip_df_thresh_rel": 0.2,
+        "relative_df_clean_thresh": 0.2,
+        "replay_thresh": 0.2,
+    }
+    event_log_df = ocel.sql(f"""
+        SELECT
+            rel."ocel:oid" as "case:concept:name",
+            ev."ocel:timestamp" as "time:timestamp",
+            ev."ocel:activity" as "concept:name"
+        FROM
+            e2o rel
+            RIGHT JOIN (
+                SELECT
+                    *
+                FROM
+                    objects
+                WHERE
+                    "ocel:type" = '{object_type}'
+                ) ob USING ("ocel:oid")
+            LEFT JOIN (
+            SELECT
+            *
+            FROM
+            events
+            ) ev USING ("ocel:eid")
+            ORDER BY
+            ("time:timestamp", "case:concept:name", "concept:name")
+                """).pl()
+
+    log_id = r4pm.import_item_from_df("EventLog", event_log_df)
+    proj_id = r4pm.bindings.log_to_activity_projection(log_id)
+    if petri_net:
+        if is_flattened(petri_net):
+            process_model = to_r4pm_format(petri_net)
+        else:
+            process_model = to_r4pm_format(flatten(petri_net, object_type))
+    else:
+        process_model = r4pm.bindings.discover_alphaplusplusplus(proj_id, config=config)
+    return proj_id, process_model
+
+
+def variant_alignment(
+    proj_id: str,
+    process_model: R4PMPetriNet,
+    options: Optional["AlignmentOptions"] = None,
+) -> List[VariantAlignmentResult]:
+    raw_result = r4pm.bindings.align_variants(process_model, proj_id, options)
+    return [VariantAlignmentResult(**r) for r in raw_result]
+
+
+def compute_fitness(alignments: List[VariantAlignmentResult], process_model: R4PMPetriNet) -> FitnessResult:
+    fitness = r4pm.bindings.compute_fitness([a.model_dump() for a in alignments], process_model)
+    return FitnessResult(**fitness)
+
+
+def compute_aggregated(
+    variant_alignments: List[VariantAlignmentResult],
+) -> Aggregated:
+    total_traces = sum(v.frequency for v in variant_alignments)
+    transition_stats: Dict[str, Dict[str, int]] = {}
+    log_move_counts: Dict[str, int] = {}
+
+    for v in variant_alignments:
+        result = v.result
+        if "Ok" not in result:
+            continue
+        freq = v.frequency
+        for move in result["Ok"]["moves"]:
+            if "SyncMove" in move:
+                t = move["SyncMove"]["transition"]
+                stats = transition_stats.setdefault(t, {"sync_fires": 0, "model_fires": 0})
+                stats["sync_fires"] += freq
+            elif "ModelMove" in move:
+                t = move["ModelMove"]["transition"]
+                stats = transition_stats.setdefault(t, {"sync_fires": 0, "model_fires": 0})
+                stats["model_fires"] += freq
+            elif "LogMove" in move:
+                idx = move["LogMove"]["trace_event_index"]
+                activity = v.activities[idx]
+                log_move_counts[activity] = log_move_counts.get(activity, 0) + freq
+
+    return Aggregated(
+        total_traces=total_traces,
+        transition_stats={k: TransitionStat(**v) for k, v in transition_stats.items()},
+        log_move_counts=log_move_counts,
+    )
+
+
+def compute_alignments(ocel: OCEL, object_type: str, petri_net: PetriNet | None):
+    (proj_id, process_model) = preprocessing(ocel, object_type, petri_net)
+    options = {
+        "cost_fn": {
+            "log_move_cost": 1,
+            "model_move_cost": 1,
+            "silent_move_cost": 0,
+            "sync_move_cost": 0,
+        }
+    }
+    try:
+        alignments = variant_alignment(proj_id, process_model, options)
+        fitness = compute_fitness(alignments, process_model)
+    except Exception as e:
+        raise AlignmentComputationError(e, traceback.format_exc()) from e
+    aggregated = compute_aggregated(alignments)
+    return AlignmentsResponse(
+        net=convert_net(process_model),
+        variant_alignments=alignments,
+        fitness=fitness,
+        aggregated=aggregated,
+    )