Add household task agent demo

Author: rsasaki0109

README.md

@@ -16,7 +16,8 @@ flagship loops directly in Colab:
 [safety filter](https://colab.research.google.com/github/rsasaki0109/PythonInteractiveRobotics/blob/main/notebooks/safety_filter_cbf.ipynb), and
 [human correction replanning](https://colab.research.google.com/github/rsasaki0109/PythonInteractiveRobotics/blob/main/notebooks/human_correction_replanning.ipynb).
 For language ambiguity, try
-[clarifying question](https://colab.research.google.com/github/rsasaki0109/PythonInteractiveRobotics/blob/main/notebooks/clarifying_question.ipynb).
+[clarifying question](https://colab.research.google.com/github/rsasaki0109/PythonInteractiveRobotics/blob/main/notebooks/clarifying_question.ipynb), or run the integrated
+[household task agent](https://colab.research.google.com/github/rsasaki0109/PythonInteractiveRobotics/blob/main/notebooks/household_task_agent.ipynb).
 If the project helps you teach, prototype, or explain robotics loops, a GitHub
 star helps others find it.
 
@@ -51,10 +52,11 @@ python3 examples/runtime/01_sense_act_loop.py
 | Active perception | `python3 examples/navigation/07_active_slam_toy.py` | map and pose uncertainty -> information-seeking action |
 | Human correction | [Open in Colab](https://colab.research.google.com/github/rsasaki0109/PythonInteractiveRobotics/blob/main/notebooks/human_correction_replanning.ipynb) | shortcut -> human correction -> cost update -> replan |
 | Language ambiguity | [Open in Colab](https://colab.research.google.com/github/rsasaki0109/PythonInteractiveRobotics/blob/main/notebooks/clarifying_question.ipynb) | ambiguous command -> ask question -> answer -> act |
+| Integrated household task | [Open in Colab](https://colab.research.google.com/github/rsasaki0109/PythonInteractiveRobotics/blob/main/notebooks/household_task_agent.ipynb) | clarify -> plan -> safety check -> retry -> human replan |
 
 ## Status
 
-38 runnable examples · 37 README GIFs · 107 smoke / regression tests ·
+39 runnable examples · 38 README GIFs · 109 smoke / regression tests ·
 5 Gymnasium-style adapters · CI green on Python 3.10, 3.11, and 3.12.
 
 See `docs/status.md` for the implementation snapshot, `docs/plan.md` for the
@@ -161,9 +163,9 @@ 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) |
 
-| Clarifying question |
-| --- |
-| ![A tabletop robot receives the ambiguous command pick the block, asks which block, receives a red answer, resolves the goal, and picks the red block.](docs/assets/gifs/clarifying_question.gif) |
+| Clarifying question | Household task agent |
+| --- | --- |
+| ![A tabletop robot receives the ambiguous command pick the block, asks which block, receives a red answer, resolves the goal, and picks the red block.](docs/assets/gifs/clarifying_question.gif) | ![A household robot asks which block to put away, plans through a room, rejects an unsafe floor step, retries a missed grasp, accepts human correction, replans, and stores the block.](docs/assets/gifs/household_task_agent.gif) |
 
 | Object permanence toy |
 | --- |

docs/assets/gifs/household_task_agent.gif

@@ -62,7 +62,7 @@ <h1>Python<wbr>Interactive<wbr>Robotics</h1>
           >Star on GitHub</a>
           <a
             class="action-link"
-            href="https://colab.research.google.com/github/rsasaki0109/PythonInteractiveRobotics/blob/main/notebooks/human_correction_replanning.ipynb"
+            href="https://colab.research.google.com/github/rsasaki0109/PythonInteractiveRobotics/blob/main/notebooks/household_task_agent.ipynb"
           >Open in Colab</a>
           <a class="action-link" href="#run">Run the first loop</a>
           <a class="action-link secondary" href="#loops">See the examples</a>
@@ -73,15 +73,15 @@ <h1>Python<wbr>Interactive<wbr>Robotics</h1>
     <section class="stats" aria-label="Project snapshot">
       <div class="stats-inner">
         <div class="stat">
-          <strong>38</strong>
+          <strong>39</strong>
           <span>runnable examples</span>
         </div>
         <div class="stat">
-          <strong>37</strong>
+          <strong>38</strong>
           <span>generated GIFs</span>
         </div>
         <div class="stat">
-          <strong>107</strong>
+          <strong>109</strong>
           <span>smoke and regression tests</span>
         </div>
         <div class="stat">
@@ -123,6 +123,7 @@ <h2>Run in Colab</h2>
             <a href="https://colab.research.google.com/github/rsasaki0109/PythonInteractiveRobotics/blob/main/notebooks/safety_filter_cbf.ipynb">Safety filter CBF</a>
             <a href="https://colab.research.google.com/github/rsasaki0109/PythonInteractiveRobotics/blob/main/notebooks/human_correction_replanning.ipynb">Human correction replanning</a>
             <a href="https://colab.research.google.com/github/rsasaki0109/PythonInteractiveRobotics/blob/main/notebooks/clarifying_question.ipynb">Clarifying question</a>
+            <a href="https://colab.research.google.com/github/rsasaki0109/PythonInteractiveRobotics/blob/main/notebooks/household_task_agent.ipynb">Household task agent</a>
           </div>
         </div>
       </section>
@@ -235,6 +236,18 @@ <h3>Clarifying question</h3>
               </figcaption>
             </figure>
 
+            <figure class="loop-card">
+              <img
+                src="assets/gifs/household_task_agent.gif"
+                alt="A household robot clarifies an ambiguous command, replans around unsafe and human-corrected zones, retries a grasp, and stores the block."
+              >
+              <figcaption>
+                <h3>Household task agent</h3>
+                <p>clarify -> plan -> safety check -> retry -> human replan</p>
+                <a href="https://github.com/rsasaki0109/PythonInteractiveRobotics/blob/main/examples/embodied_ai/36_household_task_agent.py">Open example</a>
+              </figcaption>
+            </figure>
+
             <figure class="loop-card">
               <img
                 src="assets/gifs/conformal_ask_for_help.gif"

docs/index.html

@@ -48,7 +48,8 @@
 7. `examples/embodied_ai/32_empowerment_navigation.py`
 8. `examples/embodied_ai/33_inverse_reward_from_demo.py`
 9. `examples/embodied_ai/35_clarifying_question.py`
-10. `examples/world_models/20_tiny_world_model_planning.py`
-11. `examples/world_models/23_model_error_recovery.py`
+10. `examples/embodied_ai/36_household_task_agent.py`
+11. `examples/world_models/20_tiny_world_model_planning.py`
+12. `examples/world_models/23_model_error_recovery.py`
 
 See `docs/goal_commands.md` for the first controlled-language command set.

docs/learning_paths.md

@@ -8,12 +8,12 @@ first-run experience small, fast, and failure-aware.
 
 The repository currently has:
 
-- 38 runnable examples
+- 39 runnable examples
 - 20 numbered learning-path examples
-- 18 extra examples outside the original learning-path roadmap
-- 37 generated README GIFs
-- 107 smoke and regression tests
-- 4 Colab notebooks for browser-first demos
+- 19 extra examples outside the original learning-path roadmap
+- 38 generated README GIFs
+- 109 smoke and regression tests
+- 5 Colab notebooks for browser-first demos
 - 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`,
@@ -148,6 +148,11 @@ Recent completed work:
   simulated answer, updates its structured goal, confirms the target visually,
   and picks the requested block. GIF, smoke tests, failure contract test, and a
   Colab notebook cover the loop.
+- `examples/embodied_ai/36_household_task_agent.py` was added. The agent gets
+  the ambiguous command `put the block away`, asks which block, plans to it,
+  rejects an unsafe floor step, replans, retries a missed grasp, accepts human
+  correction during delivery, replans again, and stores the block. GIF, smoke
+  test, failure contract test, and a Colab notebook cover the loop.
 - `MovingObstacleWorld` was extracted from `examples/navigation/08_interactive_mpc.py`
   into `pir/worlds/moving_obstacle.py`, and `MovingObstacleWorldGymnasiumAdapter`
   was added in `pir/adapters/gymnasium_adapter.py`. The adapter exposes a

docs/plan.md

@@ -49,7 +49,8 @@ Use this longer description when space allows:
       workflow is on `main`.
 - [x] Add Colab notebooks:
       `pick_and_retry`, `safety_filter_cbf`,
-      `human_correction_replanning`, and `clarifying_question`
+      `human_correction_replanning`, `clarifying_question`, and
+      `household_task_agent`
       ([#4](https://github.com/rsasaki0109/PythonInteractiveRobotics/issues/4)).
 - [x] Add copyable public-launch post snippets
       ([#5](https://github.com/rsasaki0109/PythonInteractiveRobotics/issues/5)).
@@ -69,6 +70,7 @@ Good first posts:
 - `language goal -> visual tokens -> skill failure -> close-view retry`
 - `shortcut -> human correction -> cost update -> replan`
 - `ambiguous command -> ask question -> answer -> act`
+- `clarify -> plan -> safety check -> retry -> human replan`
 
 Target channels:
 
@@ -186,6 +188,26 @@ GIF: `docs/assets/gifs/clarifying_question.gif`
 Colab:
 `https://colab.research.google.com/github/rsasaki0109/PythonInteractiveRobotics/blob/main/notebooks/clarifying_question.ipynb`
 
+### Household Task Agent
+
+One small task trace combines language grounding, planning, safety, grasp
+retry, and human correction:
+
+```text
+put the block away -> Which block? -> plan -> safety check -> retry -> replan -> place
+```
+
+Run it:
+
+```bash
+python3 examples/embodied_ai/36_household_task_agent.py "put the block away" --answer red
+```
+
+GIF: `docs/assets/gifs/household_task_agent.gif`
+
+Colab:
+`https://colab.research.google.com/github/rsasaki0109/PythonInteractiveRobotics/blob/main/notebooks/household_task_agent.ipynb`
+
 ## Contributor Funnel
 
 Keep public issues small and specific. Good first issues should improve an

docs/public_launch.md

@@ -5,11 +5,11 @@ see what exists, what is verified, and what should come next.
 
 ## Snapshot
 
-- Runnable examples: 38
+- Runnable examples: 39
 - Learning-path roadmap examples: 20
-- README GIFs: 37
-- Smoke and regression tests: 107 (94 example/adapter + 13 planning)
-- Colab notebooks: 4
+- README GIFs: 38
+- Smoke and regression tests: 109 (96 example/adapter + 13 planning)
+- Colab notebooks: 5
 - Core dependencies: `numpy`, `matplotlib`
 - Contributor extra: `pip install -e ".[dev]"`
 - CI: Python 3.10, 3.11, 3.12
@@ -22,7 +22,7 @@ see what exists, what is verified, and what should come next.
   `BlockedPathWorldGymnasiumAdapter`, `MovingObstacleWorldGymnasiumAdapter`
 - Shared grid-planning module: `pir.planning.astar`,
   `pir.planning.bfs_reachable_count`, `pir.planning.manhattan` -
-  imported by eleven examples (04, 05, 06, 09, 10, 24, 27, 28, 32, 33, 34)
+  imported by twelve examples (04, 05, 06, 09, 10, 24, 27, 28, 32, 33, 34, 36)
 
 `examples/embodied_ai/01_goal_command_pick.py` is an extra flagship
 goal-command example. The numbered 20-example roadmap is tracked in
@@ -35,7 +35,7 @@ goal-command example. The numbered 20-example roadmap is tracked in
 | Runtime | 2 | smallest observe-act-observe loop, trace replay |
 | Navigation | 14 | reactive avoidance, dynamic obstacles, replanning, exploration, belief, active SLAM, MPC, recovery, localization recovery, information-gain detour, multi-agent avoidance, CBF safety filter, options with interrupts, human correction replanning |
 | Manipulation | 11 | retry, reactive grasping, IK servo, moving target reaching, search, push recovery, suction sorting, belief grasp selection, active viewpoint grasp, clear path before pick, conformal ask-for-help |
-| Embodied AI | 9 | controlled goals, memory, POMDP search, tiny VLA loop, object permanence, curiosity exploration, empowerment shaping, inverse reward from demo, clarifying questions |
+| Embodied AI | 10 | controlled goals, memory, POMDP search, tiny VLA loop, object permanence, curiosity exploration, empowerment shaping, inverse reward from demo, clarifying questions, integrated household tasks |
 | World models | 2 | action-conditioned dynamics, prediction error, model update, replanning, regime-shift detection, system identification |
 
 ## Verification

docs/status.md

@@ -60,6 +60,7 @@ Run any example headless with its `--no-render` flag when available.
 | `embodied_ai/32_empowerment_navigation.py` | `python examples/embodied_ai/32_empowerment_navigation.py` | k-step empowerment -> shaped A* -> prefer open routes |
 | `embodied_ai/33_inverse_reward_from_demo.py` | `python examples/embodied_ai/33_inverse_reward_from_demo.py` | demo feature expectation -> learned weights -> shaped A* to new goal |
 | `embodied_ai/35_clarifying_question.py` | `python examples/embodied_ai/35_clarifying_question.py "pick the block" --answer red` | ambiguous command -> ask question -> answer -> act |
+| `embodied_ai/36_household_task_agent.py` | `python examples/embodied_ai/36_household_task_agent.py "put the block away" --answer red` | clarify -> plan -> safety check -> retry -> human replan |
 
 ## World Models