Merge remote-tracking branch 'upstream/hotfixes' into release

docs/source/api.rst

@@ -291,23 +291,26 @@ Some object-centric process discovery algorithms are also offered:
   * :meth:`pm4py.ocel.discover_objects_graph`; discovers an object-based graph from the object-centric event log.
 
 
-OpenAI Integration (:mod:`pm4py.openai`)
+LLM Integration (:mod:`pm4py.llm`)
 ------------------------------------------
 
 The following methods provides just the abstractions of the given objects:
 
-  * :meth:`pm4py.openai.abstract_dfg`; provides the DFG abstraction of a traditional event log
-  * :meth:`pm4py.openai.abstract_variants`; provides the variants abstraction of a traditional event log
-  * :meth:`pm4py.openai.abstract_log_attributes`; provides the abstraction of the attributes/columns of the event log
-  * :meth:`pm4py.openai.abstract_ocel`; provides the abstraction of an object-centric event log (list of events and objects)
-  * :meth:`pm4py.openai.abstract_ocel_ocdfg`; provides the abstraction of an object-centric event log (OC-DFG)
-  * :meth:`pm4py.openai.abstract_ocel_features`; provides the abstraction of an object-centric event log (features for ML)
-  * :meth:`pm4py.openai.abstract_event_stream`; provides an abstraction of the (last) events of the stream related to a traditional event log
-  * :meth:`pm4py.openai.abstract_petri_net`; provides the abstraction of a Petri net
+  * :meth:`pm4py.llm.abstract_dfg`; provides the DFG abstraction of a traditional event log
+  * :meth:`pm4py.llm.abstract_variants`; provides the variants abstraction of a traditional event log
+  * :meth:`pm4py.llm.abstract_log_attributes`; provides the abstraction of the attributes/columns of the event log
+  * :meth:`pm4py.llm.abstract_log_features`; provides the abstraction of the machine learning features obtained from an event log
+  * :meth:`pm4py.llm.abstract_case`; provides the abstraction of a case (collection of events)
+  * :meth:`pm4py.llm.abstract_ocel`; provides the abstraction of an object-centric event log (list of events and objects)
+  * :meth:`pm4py.llm.abstract_ocel_ocdfg`; provides the abstraction of an object-centric event log (OC-DFG)
+  * :meth:`pm4py.llm.abstract_ocel_features`; provides the abstraction of an object-centric event log (features for ML)
+  * :meth:`pm4py.llm.abstract_event_stream`; provides an abstraction of the (last) events of the stream related to a traditional event log
+  * :meth:`pm4py.llm.abstract_petri_net`; provides the abstraction of a Petri net
+  * :meth:`pm4py.llm.abstract_log_skeleton`; provides the abstraction of a log skeleton model
 
-The following methods can be executed directly against the OpenAI APIs:
+The following methods can be executed directly against the LLM APIs:
 
-  * :meth:`pm4py.openai.execute_prompt`; executes a prompt against OpenAI, returning the response as string
+  * :meth:`pm4py.llm.openai_query`; executes a prompt against OpenAI, returning the response as string
 
 
 Basic Connectors (:mod:`pm4py.connectors`)
@@ -572,16 +575,19 @@ Overall List of Methods
    pm4py.ocel.ocel_o2o_enrichment
    pm4py.ocel.ocel_e2o_lifecycle_enrichment
    pm4py.ocel.cluster_equivalent_ocel
-   pm4py.openai
-   pm4py.openai.abstract_dfg
-   pm4py.openai.abstract_variants
-   pm4py.openai.abstract_ocel
-   pm4py.openai.abstract_ocel_ocdfg
-   pm4py.openai.abstract_ocel_features
-   pm4py.openai.abstract_event_stream
-   pm4py.openai.abstract_petri_net
-   pm4py.openai.abstract_log_attributes
-   pm4py.openai.execute_prompt
+   pm4py.llm
+   pm4py.llm.abstract_dfg
+   pm4py.llm.abstract_variants
+   pm4py.llm.abstract_ocel
+   pm4py.llm.abstract_ocel_ocdfg
+   pm4py.llm.abstract_ocel_features
+   pm4py.llm.abstract_event_stream
+   pm4py.llm.abstract_petri_net
+   pm4py.llm.abstract_log_attributes
+   pm4py.llm.abstract_log_features
+   pm4py.llm.abstract_case
+   pm4py.llm.abstract_log_skeleton
+   pm4py.llm.openai_query
    pm4py.connectors.extract_log_outlook_mails
    pm4py.connectors.extract_log_outlook_calendar
    pm4py.connectors.extract_log_windows_events

pm4py/llm.py

@@ -16,7 +16,7 @@
 '''
 
 import pandas as pd
-from pm4py.objects.log.obj import EventLog, EventStream
+from pm4py.objects.log.obj import EventLog, EventStream, Trace
 from typing import Union, Optional
 from pm4py.utils import get_properties, constants
 from pm4py.utils import __event_log_deprecation_warning
@@ -276,3 +276,87 @@ def abstract_log_attributes(log_obj: Union[pd.DataFrame, EventLog, EventStream],
 
     from pm4py.algo.querying.llm.abstractions import log_to_cols_descr
     return log_to_cols_descr.apply(log_obj, parameters=parameters)
+
+
+def abstract_log_features(log_obj: Union[pd.DataFrame, EventLog, EventStream], max_len: int = constants.OPENAI_MAX_LEN, include_header: bool = True, activity_key: str = "concept:name", timestamp_key: str = "time:timestamp", case_id_key: str = "case:concept:name") -> str:
+    """
+    Abstracts the machine learning features obtained from a log (reporting the top features until the desired length is obtained)
+
+    :param log_obj: log object
+    :param max_len: maximum length of the (string) abstraction
+    :param activity_key: the column to be used as activity
+    :param timestamp_key: the column to be used as timestamp
+    :param case_id_key: the column to be used as case identifier
+    :rtype: ``str``
+
+    .. code-block:: python3
+
+        import pm4py
+
+        log = pm4py.read_xes("tests/input_data/roadtraffic100traces.xes")
+        print(pm4py.llm.abstract_log_features(log))
+    """
+    if type(log_obj) not in [pd.DataFrame, EventLog, EventStream]: raise Exception("the method can be applied only to a traditional event log!")
+    __event_log_deprecation_warning(log_obj)
+
+    parameters = get_properties(
+        log_obj, activity_key=activity_key, timestamp_key=timestamp_key, case_id_key=case_id_key)
+    parameters["max_len"] = max_len
+    parameters["include_header"] = include_header
+
+    from pm4py.algo.querying.llm.abstractions import log_to_fea_descr
+    return log_to_fea_descr.apply(log_obj, parameters=parameters)
+
+
+def abstract_case(case: Trace, include_case_attributes: bool = True, include_event_attributes: bool = True, include_timestamp: bool = True, include_header: bool = True, activity_key: str = "concept:name", timestamp_key: str = "time:timestamp") -> str:
+    """
+    Textually abstracts a case
+
+    :param case: case object
+    :param include_case_attributes: (boolean) include or not the attributes at the case level
+    :param include_event_attributes: (boolean) include or not the attributes at the event level
+    :param include_timestamp: (boolean) include or not the event timestamp in the abstraction
+    :param include_header: (boolean) includes the header of the response
+    :param activity_key: the column to be used as activity
+    :param timestamp_key: the column to be used as timestamp
+    :rtype: ``str``
+
+    .. code-block:: python3
+
+        import pm4py
+
+        log = pm4py.read_xes("tests/input_data/roadtraffic100traces.xes", return_legacy_log_object=True)
+        print(pm4py.llm.abstract_case(log[0]))
+    """
+    parameters = {}
+    parameters["include_case_attributes"] = include_case_attributes
+    parameters["include_event_attributes"] = include_event_attributes
+    parameters["include_timestamp"] = include_timestamp
+    parameters["include_header"] = include_header
+    parameters[constants.PARAMETER_CONSTANT_ACTIVITY_KEY] = activity_key
+    parameters[constants.PARAMETER_CONSTANT_TIMESTAMP_KEY] = timestamp_key
+
+    from pm4py.algo.querying.llm.abstractions import case_to_descr
+    return case_to_descr.apply(case, parameters=parameters)
+
+
+def abstract_log_skeleton(log_skeleton, include_header: bool = True) -> str:
+    """
+    Textually abstracts a log skeleton process model
+
+    :param log_skeleton: log skeleton
+    :param include_header: (boolean) includes the header of the response
+    :rtype: ``str``
+
+    .. code-block:: python3
+
+        import pm4py
+
+        log = pm4py.read_xes("tests/input_data/roadtraffic100traces.xes", return_legacy_log_object=True)
+        log_ske = pm4py.discover_log_skeleton(log)
+        print(pm4py.llm.abstract_log_skeleton(log_ske))
+    """
+    parameters = {}
+
+    from pm4py.algo.querying.llm.abstractions import logske_to_descr
+    return logske_to_descr.apply(log_skeleton, parameters=parameters)