Skip to content

Getting started

This walkthrough goes from an empty environment to a discovered, conformance- checked object-centric model. For installation options (private wheel registry, source builds, the external DuckDB requirement), see the installation guide.

1. Install

python3.11 -m venv .venv
. .venv/bin/activate
pip install --only-binary=:all: ocpm-engine==1.1.0   # from your configured private index

Or, for development, clone the repository and run pip install -e '.[dev]'.

2. Analyze a file, no database required

The standalone facade accepts versioned JSON requests and returns ordinary Python dictionaries while algorithms run in Rust:

from ocpm_engine import StandaloneEngine

engine = StandaloneEngine.from_ocel2_json("events.json")

# Activity profile for one object type
profile = engine.profile({"object_types": ["Order"]})

# Object-centric DFG discovery
model = engine.discover(
    {
        "view": {"object_types": ["Order"]},
        "algorithm": "object_centric_dfg",
    }
)

XES and SQLite loaders follow the same pattern (from_xes, from_sqlite); the full constructor and method surface is in the standalone module reference.

3. Score conformance from compact aggregates

Aggregate rows can be scored directly without event-level data:

from ocpm_engine import TransitionCount, dfg_conformance

rows = [
    TransitionCount("Create", "Approve", "directly_follows", 900, 95),
    TransitionCount("Create", "Reject", "directly_follows", 100, 5),
]
result = dfg_conformance(rows, coverage=0.95)

4. Connect a provider

With pg_ocpm installed in PostgreSQL, the engine negotiates the installed capability surface and pushes selective scans and sufficient-statistic aggregation into the database:

from ocpm_engine import OcpmEngine, EventLogRequest, EventLogWindow

engine = OcpmEngine(dataset_id=42, tenant_id=7)
engine.verify_pg_ocpm(cursor)
capabilities = engine.inspect_pg_ocpm(cursor)

request = EventLogRequest(
    object_type="Order",
    windows=(
        EventLogWindow(training_start, training_end),
        EventLogWindow(test_start, test_end),
    ),
)
execution = engine.execute_event_log_summary(cursor, request, capabilities=capabilities)

An existing DuckDB catalog over Parquet snapshots works through StandaloneEngine.from_duckdb_parquet(...); see the README for the full configuration shape and the server-side-cursor pattern for large results.

Where to go next