Recovery Interface#

A skill ends blocked when the shield holds the vehicle at a stop. The harness then does not stop the mission. It makes a stuck report and a menu of recovery options. A recovery mode selects one option, and the executor of the harness drives it. The checkers and the shield keep the last word on each motion.

File	Content
`Harness/acres_harness/recovery.py`	The report and the menu. The schema is `schemas/recovery_v1.schema.json`.
`Harness/acres_harness/recovery_run.py`	The sequence of a recovery and the executor.
`Harness/acres_harness/reroute.py`	The closed lanes.
`Harness/acres_harness/recovery_views.py`	The two pictures of a report.
`Harness/acres_harness/recovery_modes/`	The modes.

To use a mode, give the scenario the key "recovery": {"mode": "<name>", "options": {...}}. The command line option --recovery-mode NAME does the same.

The report (acres-stuck-report-1) has these parts:

The place: the pose, the skill, the field and the leg.
The thing that blocks: its class, its distance, its size along and across the path, the free width on each side, and its motion.
The things that were tried: the ways, the refusals by name, and the last recovery with its result.
The verdict.

The menu (acres-recovery-menu-1) has these options:

Option	Function
`wait`	Wait 60 s or 180 s.
`slow_pass`	Pass the thing on one side at a walking speed.
`reverse_then_pass`	Reverse along the driven track, then pass.
`reroute`	Close the blocked lanes and drive a new route. The option gives the planned time.
`skip_field`	Go on to the next field.

A judge (the source of a local planner) can fill predicted_room_m, predicted_time_s, risk and judged_by of each option. The menu also gives the time that is left of the mission.

Modes#

Mode	Decision	Notes
`classical`	Fixed rules on the menu. Wait for things that move, pass with the room `room_min_m`, reverse, reroute, skip.	No model. The options of the mode are its `Params`.
`menu`	A language model. It gets the report, the judged menu and two pictures: the map around the vehicle and the LiDAR from above. It calls `recover` with an option, or it makes a new plan.	The default mode of a run with a model. The variants `menu:no_pictures` and `menu:no_numbers` (no judge) remove one input.

A mode is a class with @register("name") (recovery_modes/base.py). It has these members:

Member	Function
`present`	What the decider sees.
`tools`	The tools of the decider.
`handle`	Changes a tool call into a choice.
`system_text`	The system text of a model.
`flexible`	`True` starts the flexible harness. A lane that was closed 240 s ago opens again when it alone refuses a route. Each wake-up gets the skipped fields and the progress of the route. `read {what: fields}` gets the travel table.
`wake_map_picture`	`False` gives a mode no map picture at a stop, and no `look` while the menu is open.

The Executor#

The executor is the same for each mode.

wait: the wait ends early when the thing is gone. The executor uses the memory of the returns and the scan on the held route. The held skill then continues. The stop that ended the wait does not wake the decider.
slow_pass: the source of the local planner drives the pass. It keeps one side and the pass speed until the vehicle is past the thing.
reverse_then_pass, skip_field and reroute: the executor plans a new route from the pose. Its reverse stretch follows the driven track.
The escape search tries longer reverse stretches. It stops at the first route whose first leg keeps clear of the thing and goes at most 5 m into crop. A reroute with no such route is refused.
Each route from a pose gets the crop check.
skip_field: the executor closes each lane in the reach of the thing. Then it drives to the next field that a route can reach.
A run ends with limit_stalled when the vehicle drove less than 50 m in limits.stall_s.

Plugins#

A plugin adds a local planner or a mode from outside ACRES (acres_harness.plugins). Give the name of its module in ACRES_HARNESS_PLUGINS, and its folders in ACRES_HARNESS_PLUGIN_PATH. Each process of a run imports the module. The module then registers what it adds:

from acres_harness import plugins
from acres_harness.recovery_modes import register
from acres_harness.recovery_modes.menu import MenuMode

plugins.local_planner("mine", skills_dir=..., drive_as={"goto": "my_goto", "scout": "my_scout",
                      "return_home": "my_home"}, source=lambda base: MySource(base), setup=lambda world: None)

@register("my_method")
class MyMethod(MenuMode):
    flexible = True

A scenario with "local_planner": "mine" then drives with the learned skills of skills_dir (acres_simulator.learned). MySource fills and judges the reports. A scenario with "recovery": {"mode": "my_method"} uses the mode.

The tests are Harness/tests/test_plugins.py, test_recovery.py and test_escape.py.

Recovery Interface#

The Report and the Menu#

Modes#

The Executor#

Plugins#