Search tree debugger API

Many planners dump the search tree into some open formats (like GraphViz) at the end to let users diagnose the planner behavior on their domain model, but that is a static output that is difficult to use or correlate with log files. The PDDL extension now exposes an end point to which planning engines may send diagnostic data about the states encountered in the search and the PDDL extension renders it interactively.

Search debugger API

When started, the search debugger exposes following endpoints:

POST /state/initial

This adds the initial state into the tree. This is an example payload:

{
    "id": "0",
    "parentId": null,
    "g": 0,
    "earliestTime": 0.001000
}

POST /state

This adds further states to the tree and associates them with their parent state. Depending on your planner's algorithm these could be open states queued, or states that the search progressed to, but did not evaluate their heuristic value.

{
    "id": "1",
    "parentId": "0",
    "g": 1,
    "earliestTime": 0.002000,
    "appliedAction": {
        "actionName": "action-name arg1 arg2",
        "shotCounter": 0, // for multi-shot actions, this is the index of this application in this search branch
        "earliestTime": 0.002000,
        "kind": "START" // for durative actions use: START, END, INSTANTANEOUS, TIMED
    },
    "planHead": [
        {
            "actionName": "action-name arg1 arg2",
            "shotCounter": 0,
            "earliestTime": 0.002000,
            "kind": "START" 
        }
    ]
}

POST /state/heuristic

{
    "id": "1",
    "h": 10, // optional heuristic value. When not provided, the state is rendered as a dead-end.
    "totalMakespan": 0.10, // total makespan of the planhead + relaxed plan
    "relaxedPlan": [ ... ], // same syntax as for planHead
    "helpfulActions": [
        {
            "actionName": "action2 arg1 arg2",
            "kind": "START"
        }
    ]
}

POST /state/visitedOrWorse

This endpoint expects the same structure as POST /state. It labels the given state as dropped by the search on the grounds of state memoisation. The state was visited (or is worse than a previously visited state).

POST /plan

This accepts the same payload as the /state above. The planhead of the supplied state is rendered on the tree in green.

GET /about

This may be used for a health check to see if the service is listening.

Configuring the search debugger

Port number

The search debugger is launched dynamically on a random port for increased security, but when running the planner from its own debug configuration, it may be fixed using the pddlSearchDebugger.defaultPort setting.

Planner command-line syntax

When you implement the support for sending such search diagnostic data from your planner and expose it via its command-line interface, configured the command-line syntax using the pddlSearchDebugger.plannerCommandLine setting, where the $(port) will be replaced by the actual port number.

Pattern for log file correlation

We found that the search tree is immensely helpful to navigate a textual log file. When log file is open using one of the buttons on the debugger window, clicking on a state scrolls the log file to the relevant part. You can modify the pattern that is used to find the relevant part using the pddlSearchDebugger.stateIdPattern regular expression pattern setting.

State ID Pattern

This setting lets you customize how the state id is interpreted, in case it is not just a plain number.