add conformal ask-for-help example

A new manipulation example that demonstrates calibrated uncertainty as a
runtime "ask for help" signal. The agent offline-calibrates a conformal
threshold q_hat from a small holdout, then for each item on a toy
conveyor builds a prediction set {c : score_c >= 1 - q_hat}. Singletons
are placed directly; non-singletons trigger an ask of a toy oracle that
returns the true label.

This is structurally different from 08_belief_grasp_selection.py and
09_active_viewpoint_for_grasp.py, which reduce uncertainty by acting in
the world (another grasp, another viewpoint). Here uncertainty is
reduced by deferring to a human.

Exposes counters q_hat, sorted_count, help_request_count,
correct_no_help_count, correct_after_help_count, wrong_sort_count, and
coverage_violation_count. Structured failures: wrong_sort (recoverable
- the agent committed without asking and got the wrong bin), timeout,
invalid_action.

Tests: smoke test pins seed=0 and asserts sorted_count=16,
help_request_count>=1, no wrong sorts or coverage violations, that the
ask action (2) actually appears, and that both singleton and
non-singleton prediction sets are produced. A second test verifies
empirical 1-alpha coverage on the calibration set by construction.

Counts: 33 examples / 32 GIFs / 82 tests / 11 manipulation examples.

Author: rsasaki0109

README.md

@@ -11,10 +11,10 @@ robotics loops rather than standalone algorithms.
 
 ## Current Status
 
-- 32 runnable examples
+- 33 runnable examples
 - 20 learning-path roadmap examples
-- 31 README GIFs generated from runnable examples
-- 80 smoke and regression tests
+- 32 README GIFs generated from runnable examples
+- 82 smoke and regression tests
 - Core dependencies only: `numpy` and `matplotlib`
 
 See `docs/status.md` for the implementation snapshot and `docs/plan.md` for

docs/assets/gifs/conformal_ask_for_help.gif

@@ -6,10 +6,10 @@ continuous-control Gymnasium adapter, and the curiosity exploration example.
 
 ## Current Stable Surface
 
-- 32 runnable examples
-- 20 numbered learning-path examples plus 12 extras
-- 31 generated README GIFs with nonblank checks
-- 80 smoke, adapter, and regression tests
+- 33 runnable examples
+- 20 numbered learning-path examples plus 13 extras
+- 32 generated README GIFs with nonblank checks
+- 82 smoke, adapter, and regression tests
 - CI green on Python 3.10, 3.11, and 3.12
 - Gymnasium-style adapters for `GridWorld2D`, `DynamicObstacleGridWorld`,
   `BlockedPathWorld`, `MovingObstacleWorld`, and `Tabletop2D`
@@ -35,6 +35,8 @@ continuous-control Gymnasium adapter, and the curiosity exploration example.
 | `27_multi_agent_avoidance.py` | A* over predicted-next cells of two goal-seeking agents. |
 | `MovingObstacleWorld` extraction | Moved from the example file into `pir/worlds/moving_obstacle.py`, with `MovingObstacleWorldGymnasiumAdapter` and five adapter tests. |
 | `28_curiosity_grid_exploration.py` | Visit-count-driven novelty target selection with A* commitment. |
+| `29_safety_filter_cbf.py` | Runtime CBF safety filter on a nominal go-to-goal policy; `dh/dt >= -alpha * h` projection per obstacle. |
+| `30_conformal_ask_for_help.py` | Offline conformal calibration; place when the prediction set is a singleton, defer to a toy oracle when not. Counters: `q_hat`, `help_request_count`, `coverage_violation_count`. |
 
 ## Ranked Next Work
 

docs/implementation_gap_audit.md

@@ -19,6 +19,7 @@
 7. `examples/navigation/10_localization_uncertainty_recovery.py`
 8. `examples/navigation/24_information_gain_navigation.py`
 9. `examples/navigation/27_multi_agent_avoidance.py`
+10. `examples/navigation/29_safety_filter_cbf.py`
 
 ## Manipulation Intelligence
 
@@ -32,6 +33,7 @@
 8. `examples/manipulation/08_belief_grasp_selection.py`
 9. `examples/manipulation/09_active_viewpoint_for_grasp.py`
 10. `examples/manipulation/25_clear_path_before_pick.py`
+11. `examples/manipulation/30_conformal_ask_for_help.py`
 
 ## Embodied AI
 

docs/learning_paths.md

@@ -8,11 +8,11 @@ first-run experience small, fast, and failure-aware.
 
 The repository currently has:
 
-- 32 runnable examples
+- 33 runnable examples
 - 20 numbered learning-path examples
-- 12 extra examples outside the original learning-path roadmap
-- 31 generated README GIFs
-- 80 smoke and regression tests
+- 13 extra examples outside the original learning-path roadmap
+- 32 generated README GIFs
+- 82 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`,

docs/plan.md

@@ -5,10 +5,10 @@ see what exists, what is verified, and what should come next.
 
 ## Snapshot
 
-- Runnable examples: 32
+- Runnable examples: 33
 - Learning-path roadmap examples: 20
-- README GIFs: 31
-- Smoke and regression tests: 80
+- README GIFs: 32
+- Smoke and regression tests: 82
 - Core dependencies: `numpy`, `matplotlib`
 - Contributor extra: `pip install -e ".[dev]"`
 - CI: Python 3.10, 3.11, 3.12
@@ -30,7 +30,7 @@ goal-command example. The numbered 20-example roadmap is tracked in
 | --- | ---: | --- |
 | Runtime | 2 | smallest observe-act-observe loop, trace replay |
 | Navigation | 12 | reactive avoidance, dynamic obstacles, replanning, exploration, belief, active SLAM, MPC, recovery, localization recovery, information-gain detour, multi-agent avoidance, CBF safety filter |
-| Manipulation | 10 | retry, reactive grasping, IK servo, moving target reaching, search, push recovery, suction sorting, belief grasp selection, active viewpoint grasp, clear path before pick |
+| 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 | 6 | controlled goals, memory, POMDP search, tiny VLA loop, object permanence, curiosity exploration |
 | World models | 2 | action-conditioned dynamics, prediction error, model update, replanning, regime-shift detection, system identification |
 

docs/status.md

@@ -43,6 +43,7 @@ Run any example headless with its `--no-render` flag when available.
 | `manipulation/08_belief_grasp_selection.py` | `python examples/manipulation/08_belief_grasp_selection.py` | pose belief -> grasp choice -> miss -> update -> retry |
 | `manipulation/09_active_viewpoint_for_grasp.py` | `python examples/manipulation/09_active_viewpoint_for_grasp.py` | choose view -> reduce occlusion -> grasp |
 | `manipulation/25_clear_path_before_pick.py` | `python examples/manipulation/25_clear_path_before_pick.py` | try pick -> precondition fails -> clear obstacle -> retry |
+| `manipulation/30_conformal_ask_for_help.py` | `python examples/manipulation/30_conformal_ask_for_help.py` | conformal calibration -> prediction set -> ask oracle when ambiguous |
 
 ## Embodied AI