AGENTS.md

bdsim — Agent Instructions

Part of the RVC ecosystem. Read rvc-ecosystem/AGENTS.md first — it defines shared conventions: repo ownership, math invariants, dependency boundaries, git/PR workflow, code standards, tech-debt tracking. This file only adds what's specific to this repo.

PyPI package	bdsim
Nickname	bdsim
Owner	Peter Corke (petercorke)
Default branch	main
Contribution model	Branch → PR; direct push to main at Peter's discretion

Notes specific to this repo

• Depends on spatialmath, ansitable. Integrates with robotics-toolbox-python optionally (notebook helpers, examples) — not a hard package dependency, don't add one without discussion.
• Hardware I/O blocks integrate with arduIO (Python client + Arduino sketch).
• Pure Python — builds with Hatch (hatchling) directly.
• Aspirational direction, in progress on branches, not yet merged: more real-time support, code generation, and a lightweight web-based editor. As of 2026-08-14: feat/realtime (17 commits ahead of main, hardware-target real-time I/O work, most recently targeting Raspberry Pi) and feat/shiftop (8 commits ahead, overlaps the real-time direction — block-connection operator, blockdiagram improvements, autogenerated-block formatting, a real-time I/O mock provider) are both active. The web editor (bdweb) is a different case: pyproject.toml already scaffolds it (optional-dependency group, console script, Hatch wheel target src/bdweb), but the source doesn't exist on main or on any currently-pushed branch — it only survives in one dangling, unreachable commit. Don't assume bdweb code is recoverable from a branch without checking first.
• The current Qt-based editor is a vendored student project — kept working for now, but the long-term aim is to make it redundant once the web editor lands, not to invest further in it.
• Block discovery is AST-based, not import-based. BDSim builds its block registry (sim.blocks() / --blocks) by ast.parse-ing each <package>/blocks/*.py file directly, never importing at discovery time (run_sim.py, load_blocks/parse_module). Only top-level class statements are seen — a class nested inside a module-level if/try is invisible to discovery even though it still works fine if imported directly. This silently broke blocks/spatial.py for years (a now-dead if sm: guard, fixed in PR #68) — keep block class definitions unconditional at module scope. Actual imports are deferred via a _LazyBlockClass proxy, resolved only when a block type is actually instantiated in a diagram.
• python -m bdsim / the bdsim console script (src/bdsim/__main__.py, added in PR #69) build no diagram — they exist for introspection flags handled during BDSim construction, e.g. bdsim --blocks. bdrun remains the separate, diagram-first entry point for loading and running a saved .bd file.