add object permanence toy example

Author: rsasaki0109

README.md

@@ -11,10 +11,10 @@ robotics loops rather than standalone algorithms.
 
 ## Current Status
 
-- 25 runnable examples
+- 26 runnable examples
 - 20 learning-path roadmap examples
-- 24 README GIFs generated from runnable examples
-- 67 smoke and regression tests
+- 25 README GIFs generated from runnable examples
+- 68 smoke and regression tests
 - Core dependencies only: `numpy` and `matplotlib`
 
 See `docs/status.md` for the implementation snapshot and `docs/plan.md` for
@@ -136,6 +136,10 @@ These GIFs are generated from the runnable examples, not separate animations.
 | --- | --- |
 | ![A kitchen agent parses a bring goal, searches containers, handles a closed cabinet, picks a mug, and places it on the table.](docs/assets/gifs/goal_conditioned_minikitchen.gif) | ![A toy VLA loop parses a language goal, reads visual tokens, picks from low confidence, recovers with a close view, and places the block.](docs/assets/gifs/tiny_vla_loop.gif) |
 
+| Object permanence toy |
+| --- |
+| ![An embodied agent sees an object, watches it go behind an occluder, persists its memory, walks to the remembered position, and peeks behind the occluder to recover the object.](docs/assets/gifs/object_permanence_toy.gif) |
+
 ### World models
 
 | Tiny world-model planning |

docs/assets/gifs/object_permanence_toy.gif

@@ -36,11 +36,11 @@
 2. `examples/embodied_ai/10_door_search_pomdp.py`
 3. `examples/embodied_ai/18_goal_conditioned_minikitchen.py`
 4. `examples/embodied_ai/19_tiny_vla_loop.py`
-5. `examples/world_models/20_tiny_world_model_planning.py`
+5. `examples/embodied_ai/21_object_permanence_toy.py`
+6. `examples/world_models/20_tiny_world_model_planning.py`
 
 ## Future Embodied AI Extensions
 
-1. object permanence toy
-2. curiosity grid exploration
+1. curiosity grid exploration
 
 See `docs/goal_commands.md` for the first controlled-language command set.

docs/learning_paths.md

@@ -8,11 +8,11 @@ first-run experience small, fast, and failure-aware.
 
 The repository currently has:
 
-- 25 runnable examples
+- 26 runnable examples
 - 20 numbered learning-path examples
-- 5 extra examples outside the original learning-path roadmap
-- 24 generated README GIFs
-- 67 smoke and regression tests
+- 6 extra examples outside the original learning-path roadmap
+- 25 generated README GIFs
+- 68 smoke and regression tests
 - GitHub Actions CI for Python 3.10, 3.11, and 3.12
 - core dependencies limited to `numpy` and `matplotlib`
 - optional Gymnasium-style adapters for `GridWorld2D`,
@@ -94,6 +94,10 @@ Recent completed work:
   its pose belief, runs a Bayes update from each observation, then grasps
   with the type that maximizes expected success. GIF and smoke test cover
   the loop.
+- `examples/embodied_ai/21_object_permanence_toy.py` was added. The agent
+  sees an object once, watches it go behind an occluder, persists the last
+  known position across the disappearance, walks to it, and peeks behind
+  the occluder to recover the object. GIF and smoke test cover the loop.
 
 The next agent should not redo those items. If any of them seem missing, first
 check the current branch and latest pulled commit.
@@ -250,17 +254,18 @@ Already done from the previous tier:
   grasp choice -> failure update -> retry.
 - `examples/manipulation/09_active_viewpoint_for_grasp.py` — pose belief ->
   active viewpoint -> Bayes update -> grasp.
+- `examples/embodied_ai/21_object_permanence_toy.py` — see object ->
+  memory persists across occlusion -> peek to recover.
 
 Recommended next examples:
 
 | Priority | Example | Area | Loop |
 | --- | --- | --- | --- |
-| 1 | `examples/embodied_ai/21_object_permanence_toy.py` | embodied AI | object disappears -> memory persists -> search |
-| 2 | `examples/embodied_ai/22_where_did_i_see_it.py` | embodied AI | memory query -> revisit place -> act |
-| 3 | `examples/world_models/23_model_error_recovery.py` | world model | prediction failure -> update model -> recover |
-| 4 | `examples/navigation/24_information_gain_navigation.py` | navigation | goal progress vs information gain |
-| 5 | `examples/manipulation/25_clear_path_before_pick.py` | manipulation | precondition failure -> clear obstacle -> pick |
-| 6 | `examples/navigation/27_multi_agent_avoidance.py` | navigation | observe agents -> avoid -> replan |
+| 1 | `examples/embodied_ai/22_where_did_i_see_it.py` | embodied AI | memory query -> revisit place -> act |
+| 2 | `examples/world_models/23_model_error_recovery.py` | world model | prediction failure -> update model -> recover |
+| 3 | `examples/navigation/24_information_gain_navigation.py` | navigation | goal progress vs information gain |
+| 4 | `examples/manipulation/25_clear_path_before_pick.py` | manipulation | precondition failure -> clear obstacle -> pick |
+| 5 | `examples/navigation/27_multi_agent_avoidance.py` | navigation | observe agents -> avoid -> replan |
 
 Selection rule:
 

docs/plan.md

@@ -5,10 +5,10 @@ see what exists, what is verified, and what should come next.
 
 ## Snapshot
 
-- Runnable examples: 25
+- Runnable examples: 26
 - Learning-path roadmap examples: 20
-- README GIFs: 24
-- Smoke and regression tests: 67
+- README GIFs: 25
+- Smoke and regression tests: 68
 - Core dependencies: `numpy`, `matplotlib`
 - Contributor extra: `pip install -e ".[dev]"`
 - CI: Python 3.10, 3.11, 3.12
@@ -31,7 +31,7 @@ goal-command example. The numbered 20-example roadmap is tracked in
 | Runtime | 2 | smallest observe-act-observe loop, trace replay |
 | Navigation | 9 | reactive avoidance, dynamic obstacles, replanning, exploration, belief, active SLAM, MPC, recovery, localization recovery |
 | Manipulation | 9 | retry, reactive grasping, IK servo, moving target reaching, search, push recovery, suction sorting, belief grasp selection, active viewpoint grasp |
-| Embodied AI | 4 | controlled goals, memory, POMDP search, tiny VLA loop |
+| Embodied AI | 5 | controlled goals, memory, POMDP search, tiny VLA loop, object permanence |
 | World models | 1 | action-conditioned dynamics, prediction error, model update, replanning |
 
 ## Verification

docs/status.md

@@ -48,6 +48,7 @@ Run any example headless with its `--no-render` flag when available.
 | `embodied_ai/10_door_search_pomdp.py` | `python examples/embodied_ai/10_door_search_pomdp.py` | room belief -> door/container action -> belief update |
 | `embodied_ai/18_goal_conditioned_minikitchen.py` | `python examples/embodied_ai/18_goal_conditioned_minikitchen.py "bring mug to table"` | goal -> container search -> pick -> place |
 | `embodied_ai/19_tiny_vla_loop.py` | `python examples/embodied_ai/19_tiny_vla_loop.py "place red block in blue bin"` | language -> visual tokens -> skill -> retry |
+| `embodied_ai/21_object_permanence_toy.py` | `python examples/embodied_ai/21_object_permanence_toy.py` | see object -> memory persists across occlusion -> peek |
 
 ## World Models