add examples

Author: kmolan

python/CONTRIBUTING.md

@@ -30,6 +30,16 @@ pytest benchmarks/ --benchmark-only
 
 Results written in `benchmarks/.benchmarks/` (git-ignored). See [`benchmarks/README.md`](benchmarks/README.md).
 
+## Run examples
+
+```bash
+python examples/t01_build_your_first_tree.py
+python examples/t02_basic_ports.py
+python examples/t03_passing_data.py
+```
+
+Each script prints what it's doing and exits 0 on success. `pytest tests/test_examples.py` runs all three in subprocesses and asserts clean exits — that's the rot-prevention gate.
+
 ## Pre-commit hooks
 
 Install once:
@@ -51,14 +61,14 @@ This runs `ruff`, `mypy`, the no-C++-refs check, and the project's standard hook
 |---|---|
 | `src/pybt/` | Python package (the user-facing surface) |
 | `src/_pybt/` | C++ binding code (nanobind) |
-| `tests/` | pytest suite — smoke + lifecycle |
+| `tests/` | pytest suite — smoke + lifecycle + example runner |
+| `examples/` | Runnable tutorial scripts (t01..t03 so far) |
 | `benchmarks/` | pytest-benchmark microbenchmarks |
-| `docs/` | Sphinx site (stub in Phase 1) |
+| `docs/` | Sphinx site (stub for now) |
 | `pyproject.toml` | Build config (scikit-build-core, nanobind, pytest) |
 | `CMakeLists.txt` | nanobind extension + CTest regression guards |
 
 ## Style
 
 - Python: `ruff` for lint and format, `mypy` for types.
 - C++: project root `.clang-format` (Google C++ with 2-space indent, 90-char line limit).
-- Docs: per the Documentation Standards in the project plan — standalone, brief, no C++ references outside this file and `README.md`.

python/examples/t01_build_your_first_tree.py

@@ -0,0 +1,56 @@
+"""t01 — Build your first tree.
+
+Shows the minimum needed to register a Python action, build a tree from
+XML, and tick it to completion.
+
+This tree runs two custom actions in sequence: a "check" that returns
+SUCCESS or FAILURE based on a boolean, and a "say" that prints a line.
+
+Run: python t01_build_your_first_tree.py
+Expected output:
+    [check] battery_ok=True
+    [say] hello from pybt
+    final status: SUCCESS
+"""
+
+from __future__ import annotations
+
+import pybt
+
+XML = """
+<root BTCPP_format="4">
+  <BehaviorTree ID="Main">
+    <Sequence>
+      <CheckBatteryOk/>
+      <SaySomething/>
+    </Sequence>
+  </BehaviorTree>
+</root>
+"""
+
+
+class CheckBatteryOk(pybt.SyncActionNode):
+    def tick(self) -> pybt.NodeStatus:
+        battery_ok = True
+        print(f"[check] battery_ok={battery_ok}")
+        return pybt.NodeStatus.SUCCESS if battery_ok else pybt.NodeStatus.FAILURE
+
+
+class SaySomething(pybt.SyncActionNode):
+    def tick(self) -> pybt.NodeStatus:
+        print("[say] hello from pybt")
+        return pybt.NodeStatus.SUCCESS
+
+
+def main() -> int:
+    factory = pybt.BehaviorTreeFactory()
+    factory.register_node_type(CheckBatteryOk, "CheckBatteryOk")
+    factory.register_node_type(SaySomething, "SaySomething")
+    tree = factory.create_tree_from_text(XML)
+    status = tree.tick_while_running()
+    print(f"final status: {status.name}")
+    return 0 if status == pybt.NodeStatus.SUCCESS else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

python/examples/t02_basic_ports.py

@@ -0,0 +1,57 @@
+"""t02 — Basic ports.
+
+Shows how to declare input and output ports on a custom action and pass
+data between nodes through the blackboard.
+
+The producer writes a string to its `out` port; the consumer reads the
+same value from its `in` port and prints it.
+
+Run: python t02_basic_ports.py
+Expected output:
+    [consume] got: hello world
+    final status: SUCCESS
+"""
+
+from __future__ import annotations
+
+import pybt
+
+XML = """
+<root BTCPP_format="4">
+  <BehaviorTree ID="Main">
+    <Sequence>
+      <Produce out="{shared}"/>
+      <Consume in="{shared}"/>
+    </Sequence>
+  </BehaviorTree>
+</root>
+"""
+
+
+@pybt.ports(outputs=["out"])
+class Produce(pybt.SyncActionNode):
+    def tick(self) -> pybt.NodeStatus:
+        self.set_output("out", "hello world")
+        return pybt.NodeStatus.SUCCESS
+
+
+@pybt.ports(inputs=["in"])
+class Consume(pybt.SyncActionNode):
+    def tick(self) -> pybt.NodeStatus:
+        value = self.get_input("in")
+        print(f"[consume] got: {value}")
+        return pybt.NodeStatus.SUCCESS
+
+
+def main() -> int:
+    factory = pybt.BehaviorTreeFactory()
+    factory.register_node_type(Produce, "Produce")
+    factory.register_node_type(Consume, "Consume")
+    tree = factory.create_tree_from_text(XML)
+    status = tree.tick_while_running()
+    print(f"final status: {status.name}")
+    return 0 if status == pybt.NodeStatus.SUCCESS else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

python/examples/t03_passing_data.py

@@ -0,0 +1,62 @@
+"""t03 — Passing multiple values via separate ports.
+
+Extends t02 with a stateful producer (counts ticks before reporting a
+pose) and multiple primitive ports passed to a single consumer.
+
+A later release adds `register_type` for sending custom Python classes
+through a single port — until then, pass each field as its own primitive
+port (string / int / float / bool).
+
+Run: python t03_passing_data.py
+Expected output:
+    [navigate] heading to (1.5, 2.5) at 0.8 m/s
+    final status: SUCCESS
+"""
+
+from __future__ import annotations
+
+import pybt
+
+XML = """
+<root BTCPP_format="4">
+  <BehaviorTree ID="Main">
+    <Sequence>
+      <PlanPose x="{x}" y="{y}" speed="{speed}"/>
+      <Navigate x="{x}" y="{y}" speed="{speed}"/>
+    </Sequence>
+  </BehaviorTree>
+</root>
+"""
+
+
+@pybt.ports(outputs=["x", "y", "speed"])
+class PlanPose(pybt.SyncActionNode):
+    def tick(self) -> pybt.NodeStatus:
+        self.set_output("x", 1.5)
+        self.set_output("y", 2.5)
+        self.set_output("speed", 0.8)
+        return pybt.NodeStatus.SUCCESS
+
+
+@pybt.ports(inputs=["x", "y", "speed"])
+class Navigate(pybt.SyncActionNode):
+    def tick(self) -> pybt.NodeStatus:
+        x = float(self.get_input("x"))
+        y = float(self.get_input("y"))
+        speed = float(self.get_input("speed"))
+        print(f"[navigate] heading to ({x}, {y}) at {speed} m/s")
+        return pybt.NodeStatus.SUCCESS
+
+
+def main() -> int:
+    factory = pybt.BehaviorTreeFactory()
+    factory.register_node_type(PlanPose, "PlanPose")
+    factory.register_node_type(Navigate, "Navigate")
+    tree = factory.create_tree_from_text(XML)
+    status = tree.tick_while_running()
+    print(f"final status: {status.name}")
+    return 0 if status == pybt.NodeStatus.SUCCESS else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

python/tests/test_examples.py

@@ -0,0 +1,33 @@
+"""Runs every example script in a subprocess and asserts exit 0.
+
+Examples are the user-facing front door — if any of them stops working
+end-to-end, this test fails before the regression reaches a user.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+pytestmark = pytest.mark.smoke
+
+EXAMPLES_DIR = Path(__file__).resolve().parent.parent / "examples"
+EXAMPLES = sorted(EXAMPLES_DIR.glob("t*.py"))
+
+
+@pytest.mark.parametrize("script", EXAMPLES, ids=lambda p: p.name)
+def test_example_runs_clean(script: Path) -> None:
+    result = subprocess.run(
+        [sys.executable, str(script)],
+        capture_output=True,
+        text=True,
+        timeout=15,
+    )
+    assert result.returncode == 0, (
+        f"{script.name} exited {result.returncode}\n"
+        f"stdout:\n{result.stdout}\n"
+        f"stderr:\n{result.stderr}"
+    )