openprocess 0.7.0__py3-none-any.whl

openprocess/exercises/7 Conformance/Exercise 7.1 Replay, alignments and workflows/net.pnml

@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<pnml>
+  <net id="net1" type="http://www.pnml.org/version-2009/grammar/pnmlcoremodel">
+    <name><text>m1</text></name>
+    <page id="page1">
+      <place id="i"><name><text>i</text></name><initialMarking><text>1</text></initialMarking><graphics><position x="0.0" y="90.0"/><dimension x="40" y="40"/></graphics></place>
+      <place id="p1"><name><text>p1</text></name><graphics><position x="240.0" y="0.0"/><dimension x="40" y="40"/></graphics></place>
+      <place id="p2"><name><text>p2</text></name><graphics><position x="240.0" y="180.0"/><dimension x="40" y="40"/></graphics></place>
+      <place id="p3"><name><text>p3</text></name><graphics><position x="480.0" y="0.0"/><dimension x="40" y="40"/></graphics></place>
+      <place id="p4"><name><text>p4</text></name><graphics><position x="480.0" y="180.0"/><dimension x="40" y="40"/></graphics></place>
+      <place id="o"><name><text>o</text></name><graphics><position x="720.0" y="90.0"/><dimension x="40" y="40"/></graphics></place>
+      <transition id="a"><name><text>a</text></name><graphics><position x="120.0" y="90.0"/><dimension x="40" y="40"/></graphics></transition>
+      <transition id="b"><name><text>b</text></name><graphics><position x="360.0" y="0.0"/><dimension x="40" y="40"/></graphics></transition>
+      <transition id="c"><name><text>c</text></name><graphics><position x="360.0" y="180.0"/><dimension x="40" y="40"/></graphics></transition>
+      <transition id="d"><name><text>d</text></name><graphics><position x="600.0" y="90.0"/><dimension x="40" y="40"/></graphics></transition>
+      <transition id="e"><name><text>e</text></name><graphics><position x="360.0" y="90.0"/><dimension x="40" y="40"/></graphics></transition>
+      <arc id="arc1" source="i" target="a"></arc>
+      <arc id="arc2" source="a" target="p1"></arc>
+      <arc id="arc3" source="a" target="p2"></arc>
+      <arc id="arc4" source="p1" target="b"></arc>
+      <arc id="arc5" source="p2" target="c"></arc>
+      <arc id="arc6" source="b" target="p3"></arc>
+      <arc id="arc7" source="c" target="p4"></arc>
+      <arc id="arc8" source="p3" target="d"></arc>
+      <arc id="arc9" source="p4" target="d"></arc>
+      <arc id="arc10" source="d" target="o"></arc>
+      <arc id="arc11" source="p1" target="e"></arc>
+      <arc id="arc12" source="p2" target="e"></arc>
+      <arc id="arc13" source="e" target="p3"></arc>
+      <arc id="arc14" source="e" target="p4"></arc>
+    </page>
+    <finalmarkings><marking>
+      <place idref="o"><text>1</text></place>
+    </marking></finalmarkings>
+  </net>
+</pnml>

openprocess/exercises/7 Conformance/Exercise 7.1 Replay, alignments and workflows/question.md

@@ -0,0 +1,69 @@
+# Exercise 7.1 — Replay, alignments and workflows
+
+The log $L = [\langle a,b,c,d \rangle^3, \langle a,c,b,d \rangle^2, \langle
+a,e,d \rangle]$ and the net $N$ (the given net on the right) are the ones
+the α-algorithm gives for Exercise 6.1. Three candidate models of $L$ are in
+the exercise's folder as well: *m1.pnml*, *m2.pnml* and *m3.pnml*. Open them
+with *Open Folder* in the ⋯ menu if you want to look at them.
+
+**a.** Replay every variant of $L$ on $N$ with **token-based replay**. For
+each trace, fill in the tokens **p**roduced, **c**onsumed, **m**issing and
+**r**emaining. Count the token put in the source place at the start and the
+one taken from the sink at the end. (3 points)
+
+```answer
+type: replay
+compute: replay
+points: 3
+hint: A trace that fits has m = 0 and r = 0, and then p = c.
+```
+
+**b.** What is the **fitness** of $L$ on $N$ (token-based)?
+
+```answer
+type: number
+compute: fitness
+tolerance: 0.005
+hint: fitness = ½ (1 − m/c) + ½ (1 − r/p), summed over the log.
+```
+
+**c.** The trace $\langle a, b, d \rangle$ is not in $L$. Give an **optimal
+alignment** of it with $N$: the log moves on the first line, the model moves
+on the second, `≫` (or `>>`) where there is no move.
+
+```answer
+type: alignment
+trace: a, b, d
+answer: optimal
+points: 2
+hint: Which activity has to happen in the model between b and d? That is a
+  model move: ≫ above, the activity below.
+```
+
+**d.** Rank the three candidate models *m1*, *m2* and *m3* by their fitness
+on $L$, best first.
+
+```answer
+type: ranking
+over: m1.pnml, m2.pnml, m3.pnml
+by: fitness
+hint: m2 is a plain sequence; m3 lets b, c and e replace each other.
+```
+
+**e.** Build a **workflow** in the Workflow tab on the right that discovers a
+model from $L$ with the **Inductive Miner** and checks how well it fits with
+**Check fit**. Its fitness should be 1. (2 points)
+
+```answer
+type: workflow
+needs: inductive_miner, check_fit
+result: Check fit.metrics.fitness
+answer: 1
+tolerance: 0.01
+points: 2
+hint: Drag the Inductive Miner box from Discover and Check fit from Check;
+  wire the log into both, and the miner's model into Check fit.
+```
+
+The net's Conformance tab and the log's Discover tab are hidden until you
+reveal them.

openprocess/exercises/pack.md

@@ -0,0 +1,14 @@
+# OpenProcess demo exercises
+
+Seven short worksheets: Petri nets, soundness, the α-algorithm, regions,
+markings and matrices, the Inductive Miner, and conformance checking with a
+workflow. Answer in the boxes and press **Check**: most answers are checked
+straight away, and the app never shows you a result you are meant to work out
+until you ask for it.
+
+Your answers are saved in each exercise's folder (*my answers.json*, and
+*my answer.pnml* for a net you draw, *my workflow.cpnflow* for a workflow
+you build), so you can stop and carry on later.
+
+To write your own pack, copy this folder and change the `question.md` files:
+see *Help ▸ Writing Exercise Packs*.

openprocess/flow/__init__.py

@@ -0,0 +1,50 @@
+"""Workflows: boxes, their connections, and running them reproducibly.
+
+A box is a Python function with type hints::
+
+    from openprocess.flow import box, EventLog, PetriNet
+
+    @box(group="Discover")
+    def my_miner(log: EventLog, threshold: float = 0.5) -> PetriNet:
+        \"\"\"The help text.\"\"\"
+        ...
+
+A workflow is boxes wired together, built on the canvas, in a file, or in
+Python::
+
+    from openprocess.flow import Workflow, Runner, save
+    from openprocess.flow.boxes.input import typed_log
+    from openprocess.flow.boxes.discover import inductive_miner
+    from openprocess.flow.boxes.check import check_fit
+
+    wf = Workflow("demo")
+    log = wf.add(typed_log, {"text": "[<a,b,c,d>^3, <a,c,b,d>^2, <a,e,d>]"})
+    model = wf.add(inductive_miner)
+    fit = wf.add(check_fit)
+    wf.connect(log, model); wf.connect(model, fit, "model"); wf.connect(log, fit, "log")
+    run = Runner().run(wf)
+    print(run.value(fit).metrics)
+    save(wf, "demo.cpnflow", run)      # with the record that makes it reproducible
+
+See ``docs/workflows.md``.
+"""
+
+from .box import Box, BoxError, BoxSpec, Port, Setting, box
+from .explain import Explanation, current, note, show, steps
+from .library import Library, library_for, standard_library
+from .record import check, differences, load, save
+from .runner import Cache, Result, Run, Runner
+from .sweep import Sweep
+from .types import (AlignmentResult, Any, CPNet, DFG, Dataset, EventLog, Figure, Footprint, Marking,
+                    PetriNet, Predictions, Predictor, ProcessTree, Regions, ReplayResult, Scores,
+                    SimpleLog, Table, Text, TransitionSystem, register_type)
+from .workflow import Edge, Group, Node, Workflow, WorkflowError, to_python, workflow
+
+__all__ = [
+    "AlignmentResult", "Any", "Box", "BoxError", "BoxSpec", "CPNet", "Cache", "DFG", "Dataset", "Edge",
+    "EventLog", "Explanation", "Figure", "Footprint", "Group", "Library", "Marking", "Node", "PetriNet",
+    "Port", "Predictions", "Predictor", "ProcessTree", "Regions", "ReplayResult", "Result", "Run",
+    "Runner", "Scores", "Setting", "SimpleLog", "Sweep", "Table", "Text", "TransitionSystem", "Workflow",
+    "WorkflowError", "box", "check", "current", "differences", "library_for", "load", "note",
+    "register_type", "save", "show", "standard_library", "steps", "to_python", "workflow",
+]

openprocess/flow/box.py

@@ -0,0 +1,466 @@
+"""``@box``: a Python function as a box on the workflow canvas.
+
+Writing a box is writing a function with type hints, nothing more::
+
+    from openprocess.flow import box, EventLog, TransitionSystem
+
+    @box(group="Discover")
+    def learned_states(log: EventLog, clusters: int = 8, seed: int = 0) -> TransitionSystem:
+        \"\"\"Builds a transition system by clustering prefix embeddings.\"\"\"
+        ...
+
+What the decorator reads, and nothing else:
+
+================================================  ===============================================
+parameters whose type is a OpenProcess type             input connection points, named after the parameter
+``list[Type]``                                    an input that takes any number of connections
+``Type | None`` (or a default of ``None``)        an optional input
+the return type                                   the output; a dataclass of typed fields gives several
+``int``, ``float``, ``bool``, ``str`` with a default  a setting, with the default as its value
+``Literal["a", "b"]``                             a setting that is a choice
+``Path``                                          a setting that is a file in the folder
+the docstring                                     the help text
+``inspect.getsource``                             the Code tab
+================================================  ===============================================
+
+A box has no base class and no registration call: the decorator returns a
+:class:`Box`, which is still the function (call it from a script or a
+notebook and it runs the same way) with a :class:`BoxSpec` attached.  A
+mistake in the hints (an unknown type, a setting without a default) raises
+:class:`BoxError` with a plain message at import time, which the loader
+turns into a greyed-out box with the reason.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import hashlib
+import inspect
+import importlib.util
+import types
+import typing
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Literal, Union, get_args, get_origin, get_type_hints
+
+from .types import TypeInfo, is_known, type_info
+
+SETTING_TYPES = (int, float, bool, str)
+
+
+class BoxError(ValueError):
+    """The function cannot be a box; the message says why in plain words."""
+
+
+@dataclass(frozen=True)
+class Port:
+    """A connection point: an input (a parameter) or an output."""
+
+    name: str
+    type: type | None                # None for typing.Any
+    many: bool = False               # takes any number of connections (a list)
+    optional: bool = False
+    label: str = ""
+
+    @property
+    def info(self) -> TypeInfo | None:
+        return type_info(self.type) if self.type is not None else None
+
+    @property
+    def key(self) -> str:
+        info = self.info
+        return info.key if info else "any"
+
+    @property
+    def type_name(self) -> str:
+        info = self.info
+        if info:
+            return info.name
+        return "Anything" if self.type is None else getattr(self.type, "__name__", str(self.type))
+
+    def accepts(self, other: "Port") -> bool:
+        """Can an output ``other`` be connected to this input?"""
+        if self.type is None or other.type is None:
+            return self.type is other.type and other.type is None or self.type is other.type
+        return issubclass(other.type, self.type) or self.type is other.type
+
+
+@dataclass(frozen=True)
+class Setting:
+    """A parameter that is not an input: shown as a control in the side panel."""
+
+    name: str
+    kind: str                        # "int", "float", "bool", "str", "choice", "path"
+    default: Any
+    choices: tuple = ()
+    help: str = ""
+
+    def coerce(self, value: Any) -> Any:
+        """A value as the GUI or a file gives it, in the setting's type."""
+        if self.kind == "int":
+            return int(value)
+        if self.kind == "float":
+            return float(value)
+        if self.kind == "bool":
+            return value if isinstance(value, bool) else str(value).lower() in ("1", "true", "yes", "on")
+        if self.kind == "choice":
+            if self.choices and value not in self.choices:
+                for choice in self.choices:
+                    if str(choice) == str(value):
+                        return choice
+                raise ValueError(f"{self.name!r} must be one of {', '.join(map(str, self.choices))}")
+            return value
+        if self.kind == "path":
+            return Path(value) if value not in (None, "") else None
+        return str(value)
+
+
+@dataclass
+class BoxSpec:
+    """Everything the app knows about a box, read from the function."""
+
+    id: str                          # "module.function", unique in a library
+    name: str                        # plain name shown on the canvas
+    group: str
+    function: Callable
+    inputs: list[Port] = field(default_factory=list)
+    outputs: list[Port] = field(default_factory=list)
+    settings: list[Setting] = field(default_factory=list)
+    help: str = ""
+    source: str = ""
+    file: str = ""
+    line: int = 0
+    module: str = ""
+    needs: tuple[str, ...] = ()      # modules that must be importable
+    heavy: bool = False              # run it where it can be stopped (a process)
+    custom: bool = False             # from the folder's boxes/ or a package, not OpenProcess's own
+    result_type: type | None = None  # a dataclass of outputs, when there are several
+
+    def setting(self, name: str) -> Setting | None:
+        return next((s for s in self.settings if s.name == name), None)
+
+    def input(self, name: str) -> Port | None:
+        return next((p for p in self.inputs if p.name == name), None)
+
+    def output(self, name: str = "out") -> Port | None:
+        return next((p for p in self.outputs if p.name == name), None)
+
+    def defaults(self) -> dict[str, Any]:
+        return {s.name: s.default for s in self.settings}
+
+    @property
+    def fingerprint(self) -> str:
+        """Changes when the code changes: part of every cache key."""
+        return hashlib.sha256((self.source or self.id).encode("utf-8")).hexdigest()
+
+    def missing(self) -> list[str]:
+        """The modules in ``needs`` that are not installed."""
+        return [m for m in self.needs if importlib.util.find_spec(m.split(".")[0]) is None]
+
+    @property
+    def available(self) -> bool:
+        return not self.missing()
+
+    @property
+    def unavailable_reason(self) -> str:
+        missing = self.missing()
+        return f"needs {', '.join(missing)}" if missing else ""
+
+    def describe(self) -> str:
+        """One paragraph for the command line."""
+        ins = ", ".join(f"{p.name}: {p.type_name}{' (any number)' if p.many else ''}" for p in self.inputs) or "nothing"
+        outs = ", ".join(p.type_name for p in self.outputs) or "nothing"
+        settings = ", ".join(f"{s.name}={s.default!r}" for s in self.settings)
+        first = (self.help or "").strip().split("\n")[0]
+        lines = [f"{self.name}  [{self.group}]  {self.id}", f"  takes {ins}; gives {outs}"]
+        if settings:
+            lines.append(f"  settings: {settings}")
+        if first:
+            lines.append(f"  {first}")
+        if not self.available:
+            lines.append(f"  unavailable: {self.unavailable_reason}")
+        return "\n".join(lines)
+
+
+class Box:
+    """The function, with its :class:`BoxSpec`.  Calling it calls the
+    function; inside a ``@workflow`` being recorded it adds a node instead."""
+
+    def __init__(self, function: Callable, spec: BoxSpec) -> None:
+        self.function = function
+        self.spec = spec
+        self.__wrapped__ = function
+        self.__name__ = function.__name__
+        self.__qualname__ = getattr(function, "__qualname__", function.__name__)
+        self.__doc__ = function.__doc__
+        self.__module__ = function.__module__
+
+    def __call__(self, *args, **kwargs):
+        from .workflow import recording
+        builder = recording()
+        if builder is not None:
+            return builder.call(self, args, kwargs)
+        return self.function(*args, **kwargs)
+
+    def __repr__(self) -> str:
+        return f"<box {self.spec.id}>"
+
+
+# ---------------------------------------------------------------------------
+# Reading the signature
+# ---------------------------------------------------------------------------
+def _unwrap_optional(annotation):
+    """``X | None`` -> (X, True); anything else -> (annotation, False)."""
+    origin = get_origin(annotation)
+    if origin is Union or origin is types.UnionType:
+        args = [a for a in get_args(annotation) if a is not type(None)]
+        if len(args) == 1 and len(get_args(annotation)) == 2:
+            return args[0], True
+    return annotation, False
+
+
+def _port_from(name: str, annotation, default, has_default: bool) -> Port | None:
+    """An input port for a parameter, or None when it is a setting."""
+    annotation, optional = _unwrap_optional(annotation)
+    if has_default and default is None:
+        optional = True
+    origin = get_origin(annotation)
+    if origin in (list, tuple, typing.List):
+        args = get_args(annotation)
+        inner = args[0] if args else None
+        if inner is not None and (is_known(inner) or inner is Any):
+            return Port(name, None if inner is Any else inner, many=True,
+                        optional=optional or has_default, label=name.replace("_", " "))
+        return None
+    if annotation is Any:
+        return Port(name, None, optional=optional, label=name.replace("_", " "))
+    if isinstance(annotation, type) and is_known(annotation):
+        return Port(name, annotation, optional=optional, label=name.replace("_", " "))
+    return None
+
+
+def _setting_from(name: str, annotation, default, has_default: bool, doc_hints: dict) -> Setting:
+    annotation, _ = _unwrap_optional(annotation)
+    if get_origin(annotation) is Literal:
+        choices = get_args(annotation)
+        if not has_default:
+            default = choices[0]
+        return Setting(name, "choice", default, tuple(choices), doc_hints.get(name, ""))
+    if annotation is Path or annotation == "Path":
+        return Setting(name, "path", default if has_default else None, help=doc_hints.get(name, ""))
+    if annotation is bool:
+        kind = "bool"
+    elif annotation is int:
+        kind = "int"
+    elif annotation is float:
+        kind = "float"
+    elif annotation is str:
+        kind = "str"
+    else:
+        raise BoxError(
+            f"parameter {name!r} has type {_type_text(annotation)}, which is neither a OpenProcess "
+            f"type (an input) nor int, float, bool, str, Literal[...] or Path (a setting)")
+    if not has_default:
+        raise BoxError(f"setting {name!r} needs a default value (e.g. {name}: {kind} = ...)")
+    if kind == "float" and isinstance(default, int) and not isinstance(default, bool):
+        default = float(default)
+    return Setting(name, kind, default, help=doc_hints.get(name, ""))
+
+
+def _type_text(annotation) -> str:
+    return getattr(annotation, "__name__", None) or str(annotation)
+
+
+def _outputs_from(annotation) -> tuple[list[Port], type | None]:
+    if annotation is inspect.Signature.empty:
+        raise BoxError("the function needs a return type hint (-> PetriNet), or -> None")
+    if annotation is None or annotation is type(None):
+        return [], None
+    annotation, _ = _unwrap_optional(annotation)
+    if annotation is Any:
+        return [Port("out", None)], None
+    if isinstance(annotation, type) and is_known(annotation):
+        return [Port("out", annotation)], None
+    if isinstance(annotation, type) and dataclasses.is_dataclass(annotation):
+        ports = []
+        hints = get_type_hints(annotation)
+        for f in dataclasses.fields(annotation):
+            inner, _ = _unwrap_optional(hints.get(f.name, f.type))
+            if not (isinstance(inner, type) and is_known(inner)) and inner is not Any:
+                raise BoxError(f"result field {f.name!r} has type {_type_text(inner)}, "
+                               f"which is not a OpenProcess type")
+            ports.append(Port(f.name, None if inner is Any else inner, label=f.name.replace("_", " ")))
+        if not ports:
+            raise BoxError(f"result class {annotation.__name__} has no fields")
+        return ports, annotation
+    raise BoxError(f"the return type {_type_text(annotation)} is not a OpenProcess type "
+                   f"(nor a dataclass of them)")
+
+
+def _doc_hints(doc: str) -> dict[str, str]:
+    """``name: text`` lines of a docstring, as help for settings."""
+    hints: dict[str, str] = {}
+    for line in (doc or "").splitlines():
+        stripped = line.strip()
+        if ":" in stripped and not stripped.startswith(":"):
+            key, _, text = stripped.partition(":")
+            if key.isidentifier() and text.strip():
+                hints[key] = text.strip()
+    return hints
+
+
+def _plain_name(function_name: str) -> str:
+    words = function_name.replace("_", " ").strip()
+    return words[:1].upper() + words[1:]
+
+
+def make_spec(function: Callable, name: str | None = None, group: str = "Other",
+              needs: str | tuple[str, ...] | None = None, heavy: bool = False,
+              custom: bool = False, id: str | None = None, localns: dict | None = None) -> BoxSpec:
+    """Read a function's signature into a :class:`BoxSpec` (raises :class:`BoxError`).
+
+    ``localns`` resolves names in string annotations (``from __future__ import
+    annotations``) that are local to where the function was defined."""
+    try:
+        hints = get_type_hints(function, localns=localns)
+    except Exception as error:   # noqa: BLE001 - a bad annotation of any kind
+        raise BoxError(f"could not read the type hints: {error}") from error
+    signature = inspect.signature(function)
+    doc = inspect.getdoc(function) or ""
+    doc_hints = _doc_hints(doc)
+    inputs: list[Port] = []
+    settings: list[Setting] = []
+    for parameter in signature.parameters.values():
+        if parameter.kind in (parameter.VAR_POSITIONAL, parameter.VAR_KEYWORD):
+            raise BoxError(f"*{parameter.name} is not allowed: every parameter must be named")
+        if parameter.name not in hints:
+            raise BoxError(f"parameter {parameter.name!r} needs a type hint")
+        has_default = parameter.default is not parameter.empty
+        port = _port_from(parameter.name, hints[parameter.name], parameter.default, has_default)
+        if port is not None:
+            inputs.append(port)
+        else:
+            settings.append(_setting_from(parameter.name, hints[parameter.name],
+                                          parameter.default, has_default, doc_hints))
+    outputs, result_type = _outputs_from(hints.get("return", signature.return_annotation))
+    try:
+        source = inspect.getsource(function)
+    except (OSError, TypeError):
+        source = ""
+    try:
+        file = inspect.getsourcefile(function) or ""
+        line = inspect.getsourcelines(function)[1]
+    except (OSError, TypeError):
+        file, line = "", 0
+    if isinstance(needs, str):
+        needs = (needs,)
+    module = function.__module__ or ""
+    return BoxSpec(id=id or f"{module}.{function.__name__}", name=name or _plain_name(function.__name__),
+                   group=group, function=function, inputs=inputs, outputs=outputs, settings=settings,
+                   help=doc, source=source, file=file, line=line, module=module,
+                   needs=tuple(needs or ()), heavy=heavy, custom=custom, result_type=result_type)
+
+
+@dataclass(frozen=True)
+class Called:
+    """A function a box calls that holds the actual work: the algorithm the
+    box is a thin wrapper around (see :func:`algorithm_calls`)."""
+
+    name: str                        # "alpha_miner"
+    module: str                      # "openprocess.mining.discovery.alpha"
+    file: str
+    line: int
+    source: str
+
+    @property
+    def where(self) -> str:
+        """The file as shown: ``openprocess/mining/discovery/alpha.py:86``."""
+        path = Path(self.file)
+        parts = path.parts
+        shown = "/".join(parts[parts.index("openprocess"):]) if "openprocess" in parts else path.name
+        return shown + (f":{self.line}" if self.line else "")
+
+
+def _resolve(expression, namespace: dict):
+    """The object a call's target names, through the box's globals: ``name``
+    or ``module.attribute``; None when it is not a global (a parameter, a
+    result's method)."""
+    import ast
+    if isinstance(expression, ast.Name):
+        return namespace.get(expression.id)
+    if isinstance(expression, ast.Attribute):
+        base = _resolve(expression.value, namespace)
+        if isinstance(base, (types.ModuleType, type)):
+            return getattr(base, expression.attr, None)
+    return None
+
+
+def algorithm_calls(spec: BoxSpec) -> list[Called]:
+    """The functions the box's code calls that are defined outside the
+    workflow framework and the standard library, in the order they are
+    called: the algorithms the box delegates to.  The α-algorithm box, for
+    example, calls ``openprocess.mining.discovery.alpha.alpha_miner``; that is
+    the code to read when assessing correctness, so the Code tab shows it
+    under the box's own few lines."""
+    import ast
+    import sysconfig
+    import textwrap
+    if not spec.source:
+        return []
+    try:
+        tree = ast.parse(textwrap.dedent(spec.source))
+    except SyntaxError:
+        return []
+    namespace = getattr(spec.function, "__globals__", {})
+    stdlib = sysconfig.get_paths().get("stdlib", "")
+    calls: list[tuple[int, int, Called]] = []
+    seen: set[tuple[str, str]] = set()
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call):
+            continue
+        target = _resolve(node.func, namespace)
+        if target is None:
+            continue
+        target = inspect.unwrap(target)
+        if not inspect.isfunction(target):
+            continue                                   # classes, builtins and C code are not algorithms
+        module = getattr(target, "__module__", "") or ""
+        if not module or module.startswith("openprocess.flow") or module == "builtins":
+            continue
+        key = (module, target.__qualname__)
+        if key in seen:
+            continue
+        try:
+            file = inspect.getsourcefile(target) or ""
+            lines, line = inspect.getsourcelines(target)
+        except (OSError, TypeError):
+            continue
+        if stdlib and file.startswith(stdlib):
+            continue
+        seen.add(key)
+        calls.append((node.lineno, node.col_offset, Called(target.__name__, module, file, line, "".join(lines))))
+    return [called for _line, _column, called in sorted(calls, key=lambda item: item[:2])]
+
+
+def box(function: Callable | None = None, *, name: str | None = None, group: str = "Other",
+        needs: str | tuple[str, ...] | None = None, heavy: bool = False):
+    """Turn a function into a box.  Use it bare (``@box``) or with options
+    (``@box(name="α-algorithm", group="Discover", needs="pandas")``).
+
+    ``needs`` names modules the box imports; without them the box is listed
+    greyed out with "needs pandas" instead of failing at run time.  ``heavy``
+    marks a box that may take minutes, so the app runs it where it can be
+    stopped.
+    """
+    import sys
+    # Names local to the defining scope (a result dataclass defined in a function).
+    frame = sys._getframe(1)
+    localns = dict(frame.f_locals) if frame.f_code.co_name != "<module>" else None
+
+    def decorate(fn: Callable) -> Box:
+        spec = make_spec(fn, name=name, group=group, needs=needs, heavy=heavy, localns=localns)
+        return Box(fn, spec)
+    return decorate(function) if function is not None else decorate
+
+
+__all__ = ["Box", "BoxError", "BoxSpec", "Port", "Setting", "box", "make_spec"]

openprocess/flow/boxes/__init__.py

@@ -0,0 +1,7 @@
+"""OpenProcess's own boxes: thin wrappers around the engine, one module per group.
+
+Every box here is written the way a box of your own would be (see
+``docs/workflows.md``): a function with type hints and a docstring, a
+``flow.steps`` or ``flow.show`` call where a paper would put a figure, and
+nothing else.  Read them as examples.
+"""