PR 1/4 : Add python bindings to BehaviorTree.CPP

[kmolan]

I was originally going to do this all in one PR, before I realized no one wants to review a 10,000 line PR lol. So I'm splitting this work in four incremental PRs - this is the first one. It adds the minimal foundational elements that I will build upon later.

The goal: Create pybt - python bindings for BehaviorTree.CPP. In the end, we should be able to replicate all 19 examples in the examples/ folder using python. The goal is to also create automated tests to keep track of regressions, performance benchmarking, and keep the bindings updated. This way we always have an "official" python binding, that stays in sync with the C++ source code.

To run the tests: README.md
Check out the python/examples/ folder in this PR to see example scripts.

What's included in this PR

Area	Description
Build	BTCPP_PYTHON=OFF opt-in in CMakeLists.txt; python/CMakeLists.txt + python/pyproject.toml (scikit-build-core + nanobind ≥2.5, abi3/STABLE_ABI, Python ≥3.12)
Bindings (python/src/_pybt/)	BehaviorTreeFactory, Tree (tick_*, halt, opaque root_blackboard, fork-safety), SyncActionNode + StatefulActionNode , NodeStatus / NodeType / PortDirection enums, BTError hierarchy
Python facade (python/src/pybt/)	re-exports, @pybt.ports, @pybt.simple_action, py.typed
Tests (python/tests/)	test_smoke.py, test_lifecycle.py, test_examples.py (subprocess runner)
Examples (python/examples/)	t01_build_your_first_tree.py, t02_basic_ports.py, t03_passing_data.py
Benchmarks (python/benchmarks/)	harness + 4 baseline benches (tick_rate_100_node, port_get_set, python_node_overhead pair)
Docs (stubs)	python/README.md, python/CONTRIBUTING.md, python/docs/{index.md,conf.py}, python/.readthedocs.yaml
CI	.github/workflows/python_test.yml — Ubuntu 22.04 × {cp312, cp313, cp313t-soft-fail}, lint + smoke + symbol-hygiene + hidden+LTO regression
Pre-commit	ruff + codespell hooks added to .pre-commit-config.yaml

---

Open questions for reviewers

1. Naming — How do we feel about the name pybt ? I tried searching for a good name by searching on all repos available in PyPI, then landed on this one.
2. I "stole" the json round trip idea from an earlier PR: Implement Python bindings #634 . I think its novel and solves the type erasure problem for us nicely, but open to alternatives.

---

What's coming (deferred to PR2 / 3 / 4)

PR2 — Core API ·

• Full Blackboard — dict protocol, scope, @key remapping, register_type for custom types
  • This is where the json strategy will be used
• ConditionNode / DecoratorNode / ControlNode
• tick_child, node.bb, tree.subtrees

PR3 — Observability ·

• StdCoutLogger, FileLogger2
• TreeObserver + NodeStatistics
• tree.nodes / tree.manifests
• Built-in JSON converters for NodeStatus / Timestamp / Position2D
• Docstring CI gate
• Perf-regression metrics (tick_rate_100_node_hz < 0.5× baseline = hard fail)

PR4+ — Optional + ergonomics + docs + release ·

• Scripting (_failureIf / _skipIf / _successIf)
• SQLite logger, Groot2 publisher
• AsyncActionNode (generator facade), tree.tick_iter()
• Full Sphinx docs — every handwritten page + sphinx-autoapi + doctest + linkcheck
• All remaining tutorials (t04–t19, ex01–ex03)
• python_wheels.yml cibuildwheel matrix × {Linux, macOS, Windows}
• RTD deploy
• PyPI OIDC trusted-publisher release

[kmolan]

@facontidavide