python_interop

Purpose

Python interop supports test orchestration, model exploration, replay tooling, and notebook-style analysis around a machine definition. It is not the production runtime path. Production execution remains C++.

There are two Python-facing outputs:

• pure Python simulator export;
• pybind11 C++ extension skeleton generation.

Pure Python Simulator

Generate a Python model from machine JSON:

python3 tools/tsm_tool.py export examples/surgical_robot/ir/surgical_robot.machine.json \
  --format python \
  -o build/surgical_robot_model.py

The generated module contains:

• EventKind: enum of known events;
• Snapshot: active-state/context snapshot record;
• <MachineName>Model: small simulator with send(...) and snapshot().

Example use:

from surgical_robot_model import EventKind, SurgicalRobotSupervisorModel
 
model = SurgicalRobotSupervisorModel()
assert model.snapshot().active == "Offline"
 
assert model.send(EventKind.PowerOn)
assert model.snapshot().active == "SelfTest"

The simulator is intentionally lightweight. It tracks active state and transition rows. It is useful for smoke tests, UI prototypes, CI checks, and tooling workflows that need to inspect behavior without compiling C++.

pybind11 Skeleton

Generate a C++ binding skeleton:

python3 tools/tsm_tool.py generate examples/surgical_robot/ir/surgical_robot.machine.json \
  --format pybind11 \
  -o build/surgical_robot_pybind.cpp

The generated skeleton exposes:

• EventKind: Python-visible event enum;
• StateKind: Python-visible active-state enum for runtime states;
• send_kind(...): typed event dispatch bridge;
• active_kind(): active-state query bridge.

The skeleton expects a generated or hand-maintained C++ machine header. A product team should review the generated file, connect it to the desired C++ runtime object, and decide which context fields or side-effect endpoints should be visible to Python.

Recommended Use

Use pure Python export for:

• design review smoke tests;
• scenario exploration;
• notebooks;
• replay and trace visualization;
• CI checks that should not compile extension modules.

Use pybind11 generation for:

• Python-driven integration tests against C++ behavior;
• simulation harnesses that need the production C++ transition logic;
• operator tooling that needs controlled inspection of active state.

Keep safety-critical or deployment behavior in C++. Python should drive tests, analysis, and tool adapters around the C++ surface.

Tested Path

The quality suite covers:

• generated Python import and event dispatch;
• pybind11 skeleton contents;
• pybind11 extension configure/build/import when the pybind11 Python package is available.