Describe one case as a natural-language walkthrough of its events.

case_id must match a value in the log's case:concept:name column. pm4py's case_to_descr has no MAX_LEN parameter — the full case description is always returned, so truncated is always False.

drop_nan_attrs (default True, new in 0.3.2) strips <attr> = nan substrings from the output, cutting token use by ~70% on real logs without losing any non-NaN signal. Pass False for the exact pre-0.3.2 verbose output.

Natural-language description of a discovered DECLARE model.

Takes the handle returned by discover_declare. Wraps declare_to_descr.apply. pm4py's descriptor has no MAX_LEN knob, so truncated is always False and the full constraint set is described.

Directly-follows graph rendered as text.

Note: takes log_id, not dfg_id. pm4py computes the DFG internally for description. For the rendered PNG/SVG, use Phase 1's discover_dfg → visualize_dfg pair instead.

Textual description of attribute distributions (value frequencies, quantiles).

Wraps log_to_cols_descr.apply. Useful for the LLM to understand what slicing dimensions exist in the log.

Textual description of log-level features (activity set, concurrency, timing).

Wraps pm4py.algo.querying.llm.abstractions.log_to_fea_descr.apply. Truncated at max_len characters (pm4py's native limit).

Natural-language description of a discovered log skeleton.

Takes the handle returned by discover_log_skeleton. Wraps logske_to_descr.apply. No MAX_LEN parameter; always returns the full skeleton in prose.

Object-centric directly-follows graph as text.

Note: takes ocel_id, not ocdfg_id. pm4py computes the OCDFG internally for description. For the rendered version, use Phase 2's discover_ocdfg → visualize_ocdfg pair.

Textual description of OCEL features for a single object type.

object_type must be one of the OCEL's object types (see describe_ocel). Wraps ocel_fea_descr.apply(ocel, object_type). Useful before deciding which object type to flatten_ocel on.

Describe a Petri net (from discover_petri_net) in natural language.

Wraps net_to_descr.apply(net, im, fm). Enumerates places, transitions, arcs, and the initial / final markings. pm4py's net_to_descr has no MAX_LEN parameter — the full description is always returned, so truncated is always False.

Describe the top-k connections of a social-network (SNA) model in prose.

pm4py's LLM abstractions do NOT ship an sna_to_descr; this tool is hand-written. It reports:

• total resource / connection counts

• the top_k strongest connections by weight (source → target, weight)

• resources with no outgoing connections (network sinks — common endpoints)

• resources with no incoming connections (network sources — unusual entry points)

Works on any handle produced by discover_handover_network, discover_working_together_network, discover_subcontracting_network, or discover_activity_based_resource_similarity. truncated is always False since top_k bounds the output.

Tail of events in reverse-chronological order.

Answers "what happened recently in this log?" without computing variants or discovering a model. Wraps stream_to_descr.apply.

Natural-language description of a discovered temporal profile.

Takes the handle returned by discover_temporal_profile. Wraps tempprofile_to_descr.apply. The profile dict is keyed by Tuple[str, str] activity pairs; the descriptor internally formats these and never surfaces the raw tuples to JSON serialization. No MAX_LEN parameter; full profile is described.

Trace variants + frequencies + (optionally) per-variant performance.

Wraps log_to_variants_descr.apply. Variants are auto-ranked by frequency internally; truncation happens when the combined description hits max_len characters — not via a top_k parameter.

Alignment-based conformance check.

More accurate than token replay but slower — can take minutes on large logs. multi_processing=True parallelizes across cores (disabled by default since Windows multiprocessing has spawn-restrictions that can interact badly with the stdio transport).

Emits progress events so the client keeps the request alive past its default timeout.

Token-based replay conformance check.

Returns mean trace fitness (0.0..1.0) and the count of perfectly-fit traces. For detailed per-trace diagnostics, re-run the PM4Py conformance_diagnostics_token_based_replay directly — we keep the MCP response compact on purpose.

Convert a process model from one representation to another.

source_id is any model handle (Petri net, BPMN, process tree, POWL). target_kind is one of "petri_net", "bpmn", "process_tree".

Supported pairs:

• → petri_net: from bpmn, process_tree, powl

• → bpmn: from petri_net, process_tree

• → process_tree: from petri_net, bpmn, powl

Unsupported combinations raise InvalidKind. The new handle records source_handle=source_id so lineage is debuggable.

Return the compact summary for a previously loaded log.

Exact same shape as the summary attached to load_event_log's response, re-computed on demand. Raises :class:HandleNotFound if the registry has evicted the log (1-hour TTL or LRU overflow).

Return the compact summary for a previously loaded OCEL.

Exact same shape as the summary attached to load_ocel's response, re-computed on demand. Raises :class:HandleNotFound if the registry evicted the OCEL (1-hour TTL or LRU overflow).

Discover the activity-based resource-similarity network.

An edge A ↔ B weighted by how similar the activity profiles of A and B are. Captures "who does similar kinds of work" — complements handover by showing skill/role overlap.

Discover a BPMN diagram via the Inductive Miner.

Convenience wrapper over discover_process_tree_inductive + BPMN conversion. Returns a handle plus node/flow counts.

Discover a DECLARE model from an event log.

DECLARE is a declarative constraint notation capturing patterns like "response" (if A then eventually B) or "precedence" (B requires A earlier). PM4Py returns a nested dict: template → (activity-tuple → {"support": N, "confidence": N}).

min_support_ratio / min_confidence_ratio prune weak constraints (both in [0, 1]; default None uses pm4py's internal defaults).

Returns a handle plus counts of templates covered and constraints found.

Discover the directly-follows graph (DFG) of an event log.

Returns a handle for later rendering via visualize_dfg plus a shape summary (edge count, start/end activity counts).

Discover the handover-of-work network.

An edge A → B means resource A's activity was directly followed by resource B's activity within the same case. beta controls distance decay (0 = direct handover only; larger values weigh indirect handoffs).

Returns a handle under the "sna" kind plus resource / connection counts.

Discover a log skeleton — a set of behavioral constraints per activity pair.

The log skeleton captures six constraint types (equivalence, always_after, always_before, never_together, directly_follows, activ_freq). Useful as a declarative complement to Petri-net / process-tree discovery.

noise_threshold in [0, 1] prunes infrequent patterns.

Discover an object-centric directly-follows graph (OC-DFG).

Returns a handle for later rendering via visualize_ocdfg plus a shape summary: activity count, object types, and per-object-type edge counts (the "how many distinct activity pairs does this object type induce" signal).

Discover an object-centric Petri net (OCPN).

variant dispatches the underlying Inductive Miner:

• "im" (default) — classical Inductive Miner on each per-type projection

• "imd" — Inductive Miner Directly-Follows (faster, less precise)

Returns a handle to the OCPN plus per-object-type structural counts.

Discover organizational roles — activity-sharing clusters of resources.

pm4py returns a List[Role] where each role has:

• activities: list of activities that cluster together

• originator_importance: dict mapping resource → weight within the role

Returns a handle under "org_roles" plus counts and a preview of the top 5 roles by importance sum.

Discover a Petri net from an event log.

algorithm dispatches to one of three PM4Py miners:

• "inductive" (default) — Inductive Miner, sound-by-construction. Accepts noise_threshold in [0, 1] to prune infrequent behavior.

• "heuristics" — Heuristics Miner, robust to noise.

• "alpha" — classical Alpha Miner.

Returns a handle to the (net, initial_marking, final_marking) triple plus structural counts. The model is stored with kind petri_net.

Discover a POWL model (Partially Ordered Workflow Language).

POWL generalizes process trees by letting siblings have partial-order dependencies rather than strict sequence / concurrency / choice. Useful when the discovered model has unclear sibling ordering.

variant is pm4py's default (dynamic variant selection). Returns a handle plus the root operator name and top-level child count.

Discover a process tree via the Inductive Miner.

Process trees compose cleanly and convert to Petri nets / BPMN. Returns a handle to the tree plus its structural shape.

Discover the subcontracting network.

An edge A → B means: A did something, then within n events B did something, then A resumed. Captures "A hands off briefly to B and takes over again" patterns.

Discover a temporal profile — per-activity-pair mean + stddev of sojourn time.

For every ordered activity pair (A, B) seen in any case, the profile records (mean_seconds, std_seconds). Useful for anomaly detection: an execution where a pair is much slower than its profile mean is flagged.

Returns a handle plus the number of pairs observed.

Discover the working-together network.

An edge A ↔ B means resources A and B participated in the same case at least once. Captures collaboration patterns independent of order.

Write a log from the registry to disk.

format must be "xes" or "csv". If path has no directory component, the file lands in the workspace; otherwise the given path (absolute or relative to CWD) is used verbatim.

Write an OCEL from the registry to disk.

format must be one of "jsonocel", "xmlocel", "sqlite". If path has no directory component, the file lands in the workspace; otherwise the given path (absolute or relative to CWD) is used verbatim.

Filter a log by event or case attribute values.

level='event' removes individual events; level='case' removes entire cases. retain=True keeps the matching rows; False drops them. The level parameter is passed explicitly to avoid PM4Py's deprecation warning when it defaults to None.

Keep only cases whose total elapsed time is in [min_seconds, max_seconds].

Performance is measured as last_event_timestamp - first_event_timestamp of each case, in seconds. Useful for isolating slow or fast cases.

Keep only cases with an event count in [min_size, max_size].

Useful for removing outlier cases (very short or very long traces) before discovery / conformance.

Filter an OCEL by event or object attribute values.

level='event' dispatches to pm4py.filter_ocel_event_attribute; level='object' dispatches to pm4py.filter_ocel_object_attribute. retain=True keeps the matching rows, False drops them — this maps to PM4Py's positive parameter.

Connected-component filtering — the OCEL-specific power feature.

Dispatches on strategy:

• "activity" — keep events in the connected component containing any object touched by activity value (string). retain is ignored.

• "object" — keep events in the connected component containing the object with id value (string). retain is ignored.

• "otype" — filter by the connected component of an object type. value is a string; retain controls keep-vs-drop.

• "length" — keep CCs whose size is in [min, max]. value is a two-element integer list [min, max]. retain is ignored.

PM4Py's CC filters are marked experimental; expect occasional edge-case failures on malformed OCELs.

Keep or drop entire object types (and every event that only touched them).

types=['order', 'delivery'] with retain=True keeps only events/objects related to orders and deliveries; with retain=False drops them.

Keep only events whose timestamp falls in [start, end].

start and end accept ISO-8601 strings (2024-01-01T08:00:00). pm4py's underlying filter parses with '%Y-%m-%d %H:%M:%S', so we normalize via pandas first.

Filter a log by a time window.

start and end are ISO-8601 datetime strings. mode chooses which notion of "within the window" applies:

• "events" (default) — keep individual events inside the window.

• "traces_contained" — keep traces entirely within the window.

• "traces_intersecting" — keep traces with any event in the window.

• "traces_starting_in" / "traces_completing_in" — keep traces whose first/last event falls in the window.

Filter a log by trace variant.

Exactly one of top_k and variants must be given:

• top_k=N — keep (or remove, if retain=False) the N most frequent variants. Useful for ignoring rare noise.

• variants=[[act1, act2, ...], ...] — keep/remove specific variants by their full activity sequence.

Project an OCEL onto a single object type and return a traditional log handle.

This is the Phase 2 composability bridge. The resulting log_id works with every Phase 1 tool — discover, conform, filter, visualize.

Raises :class:UnsupportedFormat if object_type is not present in the OCEL.

Return summary statistics for per-case durations (seconds).

Returns count, min, max, mean, median, and the 50/75/90/95/99 percentiles. The full per-case list is NOT returned — it can be 100k+ floats on a real log and blow the response cap.

Return the average cycle time (seconds between case completions).

Unlike get_case_durations (which measures elapsed time per case), cycle time measures throughput — inter-completion delay at the process level. Useful for capacity planning.

Retrieve a previously-stored domain context.

Raises :class:ContextNotFound if the name is not registered.

Return the frequency of start and end activities across all cases.

Two dicts keyed by activity name → count. Useful for spotting unexpected entry / exit points in a process.

Return the most-common trace variants and their counts.

Caps output at top_k variants (default 20) and includes the total variant count so the caller knows if the list was truncated.

List files currently in the workspace directory.

Reports each entry's name, absolute path, size, and modification time. Subdirectories are included by name but not recursed into.

Read an event log from disk and store it under a fresh log_id handle.

Format is inferred from the file extension when format is not passed. Supported: XES (.xes, .xes.gz), CSV (.csv), Parquet (.parquet).

For CSV and Parquet, the three *_key parameters tell pm4py which columns to treat as case id / activity / timestamp. Defaults assume the pm4py-standard column names.

Returns a dict with log_id plus a compact summary (case/event counts, activities preview, time range, top 5 variants). Never returns the log itself — subsequent tools retrieve it by handle.

Read an OCEL 2.0 file from disk and store it under a fresh ocel_id handle.

Format is inferred from the file extension:

• .jsonocel / .json — JSON-OCEL (the most common format)

• .xmlocel / .xml — XML-OCEL

• .sqlite — SQLite-OCEL

Returns a dict with ocel_id plus a compact summary (object types + per-type event counts, activities preview, time range). Never returns the OCEL itself; subsequent tools retrieve it by handle.

Use flatten_ocel to project the OCEL onto a single object type and obtain a traditional log_id that composes with every Phase 1 tool.

Health-check tool. Returns the server name and version.

Used by the testing pyramid and by humans verifying that a freshly installed server is reachable from their MCP client (Claude Desktop, Claude Code, MCP Inspector).

Assemble a Markdown executive report from prose findings + artifact links.

Parameters

title Report heading. Rendered as an H1. findings Markdown-formatted narrative. Pass the prose the LLM wrote after calling abstract_* / get_* tools — bullet points, tables, paragraphs all work. Leading/trailing whitespace is stripped. artifact_paths Optional list of absolute paths to PNG/SVG/CSV files produced earlier in the session (e.g. by visualize_petri_net or export_log). Images are embedded inline; other files are listed as links. output_path Optional. Bare filename lands in the workspace; a path with separators is honored as-is. When omitted, writes to a unique file like report-abc123.md in the workspace.

Returns

dict {"path": str, "size_bytes": int, "num_artifacts": int}.

Return a small sample of case IDs from a log.

Useful for picking a concrete case_id to pass to abstract_case without having to export the log to disk first.

Strategies:

• "first": IDs in original order (cheap; no sort).

• "longest": the n cases with the most events.

• "shortest": the n cases with the fewest events.

For longest / shortest, the response includes an event_counts dict so callers can see the sort key; first omits it.

Register a domain context (SOP, glossary, process description) under name.

text_or_path is treated as a file path if it resolves to an existing readable file; otherwise as inline text. Subsequent calls with the same name overwrite the stored value. Subsequent prompt invocations prepend the stored context to their instructions.

Limits: 20 KB per context (raises WorkspaceError if exceeded), 16 named contexts max.

Simulate an event log by replaying a discovered model.

Accepts Petri net (tuple) or process tree handles. BPMN and POWL are NOT supported by pm4py.play_out directly — convert them first via convert_model(bpmn_id, target_kind="petri_net").

The returned log_id is a regular "log" kind, so the simulated log composes with every Phase 1 tool. source_handle points at the source model for lineage.

num_traces is capped at 10_000 to protect against runaway generation on cyclic models.

Render a BPMN diagram (from discover_bpmn) as PNG + SVG.

Render a directly-follows graph (from discover_dfg) as PNG + SVG.

Render a dotted chart (Graphviz/neato, PNG-only output via our helper).

Dotted charts project events onto a time-vs-value scatter using the provided attributes. Default ["concept:name", "time:timestamp"] plots activity versus event time — the most useful view on an unfamiliar log. Pass other attribute names (e.g. ["org:resource", "time:timestamp"]) to see resource timelines or any numeric/categorical column.

Requires the dot / neato binaries from Graphviz (same dependency as the Phase 1 visualization tools).

Render an OC-DFG (from discover_ocdfg) as PNG + SVG.

PM4Py colors the edges by object type, so the inline PNG visually separates the per-type flows. Frequency annotations are included by default.

Render an object-centric Petri net (from discover_oc_petri_net) as PNG + SVG.

Render a performance spectrum (Graphviz/neato, PNG-only output via our helper).

Plots the duration of each case along an ordered activity list, revealing bottleneck segments visually. activities is required — the chart is only meaningful when the caller picks a subset of activities to track. Typically the activities of interest from the dominant variant(s).

Requires the dot / neato binaries from Graphviz.

Render a Petri net (from discover_petri_net) as PNG + SVG.

Render a POWL model (from discover_powl) as PNG + SVG.

Graphviz-backed. POWL diagrams show partial-order edges between sub-workflows; the root operator is reported in the caption.

Render a process tree (from discover_process_tree) as PNG + SVG.