v0.1.0 — Tiny Robot Failure Lab

Robotics tutorials usually assume actions succeed. This one is about what happens when they don't.

Real robots miss grasps, drive into walls they couldn't see, lose track of where
they are, and misread ambiguous commands. PythonInteractiveRobotics is a tiny
lab for exactly that part of robotics — observe, act, fail, update your
belief, replan, retry — in readable Python with no ROS, no GPU, and no
simulator. Just numpy + matplotlib.

What's in this first release

A failure-first course of 10 short, runnable loops, in order, plus 39 total
examples to branch into. Start here:

git clone https://github.com/rsasaki0109/PythonInteractiveRobotics.git
cd PythonInteractiveRobotics
python3 -m pip install -e .
python3 examples/manipulation/01_pick_and_retry.py

A tabletop robot misses a grasp, updates its belief, and retries — in under 5
seconds.

Try it without installing

• ▶ Run the real Python in your browser: the live playground
  runs the actual numpy example code in-page via Pyodide — no install, no
  server. Watch a tabletop robot miss, update its belief, and retry, with belief
  entropy, compare mode, and a failure timeline.
• ✏️ Edit the robot's brain: in the playground's pick-and-retry scenario you
  can edit the agent's act() / retry schedule and re-run the real loop live.
• 📓 Open in Colab: pick and retry,
  safety filter,
  household task agent.
• 🎓 Take the tour: the 10-lesson failure-first course.

Highlights

• Fail and retry — grasp miss → belief update → retry (manipulation/01)
• Replan around a hidden wall — plan → see new obstacle → replan (navigation/04)
• Act to learn — toy active SLAM that moves to shrink uncertainty (navigation/07)
• Stay safe at runtime — a CBF safety filter the policy never knows about (navigation/29)
• Ask before acting — ambiguous command → clarify → act (embodied_ai/35)
• Put it together — a household agent that clarifies, plans, stays safe,
  retries, and replans in one run (embodied_ai/36)

Every example exposes failure through info["failure"] and returns an
inspectable Trace, so you can study a run headless without rendering.

Under the hood

• 39 runnable examples · 39 generated GIFs · 5 Colab notebooks
• 122 smoke / regression tests · CI green on Python 3.10, 3.11, and 3.12
• the live playground runs the unmodified example code in-browser (Pyodide),
  pinned to the source by a trace-contract test so it can't drift
• Core deps: numpy + matplotlib only; optional Gymnasium-style adapters and
  ROS2 / simulator bridge docs for when you outgrow the toy worlds

Where this sits

Not a replacement for ROS2, MoveIt, MuJoCo, Isaac Sim, or LeRobot — and not a
benchmark. Think of it as the missing closed-loop chapter you read after
algorithm textbooks like PythonRobotics and before a heavy stack: a small,
debuggable model of failure, belief, recovery, and replanning.

Contribute

Good first contributions are deliberately small:

• add a new failure mode to an existing world
• add a one-file lesson in the failure-first style
• improve a trace story / GIF

See CONTRIBUTING.md.
If this helped you learn, teach, or prototype, a ⭐ helps others find it.