Skip to content

petri_net_nn.cli

cli

Command-line entry points for the PETRA toolkit.

Three commands, all subcommands of a single petra parser (plus the convenience aliases declared in pyproject.toml's [project.scripts] block so petra-train / petra-score / petra-serve work without the subcommand word):

  • petra-train — load a scenario from a TOML config, train the compiled module on the scenario's trace set, and save the trained module to disk as a two-file bundle (a .pt pickle of the module plus a JSON metadata sidecar that records the scenario's input_marking and input_values specs along with the petra-nn version that produced it).

  • petra-score — load a saved bundle plus a trace file (XES / CSV / JSON), compute :func:anomaly_score for each trace using the metadata's input_marking spec, and emit a JSON document with the per-trace scores. Suitable for a cron job or a batch pipeline.

  • petra-serve — load a saved bundle and run the FastAPI REST app under uvicorn on a port. A workflow engine or monitoring system can then talk to PETRA over HTTP without any Python wiring on its side.

The design target is engine integration: a workflow team that wants to plug PETRA into Camunda / Activiti / Flowable should be able to install petra-nn, train from a scenario file, and stand up either a REST endpoint or a batch scoring job without writing any Python beyond the scenario TOML. The heavyweight JVM-side plugins (execution listeners, command interceptors, process delegates) are out of scope for this package — see docs/INTEGRATION_PATTERNS.md for the wiring recipes that bridge an engine's audit log or event stream to these CLI commands or to the REST API.

Bundle format

A trained-model bundle is two files written side-by-side:

  • <name>.pt — pickled :class:PetriNetModule. Use :func:torch.load to reconstruct. Don't load bundles from untrusted sources — pickle deserialises arbitrary Python objects.

  • <name>.meta.json — JSON sidecar with:

    { "scenario_name": "...", "scenario_description": "...", "input_marking_spec": { ... }, # from [training.input_marking] "input_values_spec": { ... }, # from [training.input_values] "petra_version": "0.1.0", "saved_at": "2026-05-20T...Z" }

Read by :command:petra-score to know which trace attributes to map onto which places at inference time.

main 

main(argv=None)

Single petra entry point. Dispatches to the chosen subcommand's handler.

Source code in petri_net_nn/cli.py 
601
602
603
604
605
606
607
608
609
def main(argv: list[str] | None = None) -> int:
    """Single ``petra`` entry point. Dispatches to the chosen
    subcommand's handler."""
    parser = _build_parser()
    args = parser.parse_args(argv)
    if not getattr(args, "func", None):
        parser.print_help(sys.stderr)
        return 2
    return args.func(args)