Skip to main content

Map action frames

Module: insight | Role: Any member | Licence: Free+ | Auth: Session cookie

Eve can ask a map the client shows to focus, select, change layers or highlight assets. She does this with four tools: map_focus, map_select, map_layers and map_highlight. Each call streams one map_action frame on POST /api/v1/chat/stream, beside the chart_data and map_data frames. A map action makes no map tile and stores nothing, so it has no map_id.

The client decides what to do with a frame. It applies it to the map already on screen, shows an Undo cue, and never opens, closes or navigates a page because of one. Eve is told the action was requested, not done, so she says "I've asked the map to …" or nothing.

Declaring map control​

Eve is offered the four tools only on a turn whose request body sets map_control: true, and a call on any other turn is refused without a frame. Leave it out, or send false, on any page without a map Eve may change.

{
"messages": [{ "role": "user", "content": "Zoom to Elmsford" }],
"map_control": true
}

map_control is an interim field. The chat request's planned context field will carry it, and the top-level field will then be retired.

Frame envelope​

Every frame is one SSE data: line:

data: {"type": "map_action", "data": {"action": "focus", "action_id": "…", …}}
FieldTypeMeaning
type"map_action"The frame type.
data.action"focus" | "select" | "layers" | "highlight"Which change to make.
data.action_idstring (UUID)Unique per call. Use it to tie an Undo to the frame that caused it.

The other data fields depend on action. A tool call with bad arguments streams no frame. Eve gets the error instead.

focus​

Frame a named place or a bounding box. Exactly one of region or bbox is present.

FieldTypeMeaning
regionstringA place as the user named it: a utility, state, county, ZIP or town. The client resolves it, for example with its own search.
bbox[west, south, east, north]WGS84 degrees. west < east and south < north.

select​

Select a utility, or one substation in it, as if the user had clicked it.

FieldTypeMeaning
utility_idstringAlways present. The utility id /api/gridbase/v1 returns, for example coned.
substation_idstringOptional. The id GET /api/gridbase/v1/network/distribution/us/substations returns: the utility's own id, else the HIFLD substation_id.

layers​

Turn layers on or off. Only the layers to change are listed.

FieldTypeMeaning
layersobjectLayer id → true (show) or false (hide).

The layer ids are fixed: territories, transmission, substations, circuits, ev, solar, battery, thermostat. Eve cannot send any other id.

highlight​

Highlight feeders and substations. At least one of the two lists is non-empty, and each holds up to 50 ids.

FieldTypeMeaning
feeder_idsstring[]Feeder ids, as query_hosting_capacity returns them. Always present, possibly empty.
substation_idsstring[]Substation ids, as for select. Always present, possibly empty.
utility_idstringOptional. The utility the ids belong to.

Fixtures​

Copy these as test fixtures. Each is the parsed JSON of one data: line.

{"type": "map_action", "data": {"action": "focus", "action_id": "6f1c1f9e-3b8a-4d0e-9a51-0c7f2f1d6a01", "region": "Elmsford, NY"}}
{"type": "map_action", "data": {"action": "focus", "action_id": "6f1c1f9e-3b8a-4d0e-9a51-0c7f2f1d6a02", "bbox": [-73.83, 41.04, -73.80, 41.06]}}
{"type": "map_action", "data": {"action": "select", "action_id": "6f1c1f9e-3b8a-4d0e-9a51-0c7f2f1d6a03", "utility_id": "coned"}}
{"type": "map_action", "data": {"action": "select", "action_id": "6f1c1f9e-3b8a-4d0e-9a51-0c7f2f1d6a04", "utility_id": "coned", "substation_id": "HARRISON"}}
{"type": "map_action", "data": {"action": "layers", "action_id": "6f1c1f9e-3b8a-4d0e-9a51-0c7f2f1d6a05", "layers": {"circuits": true, "ev": false}}}
{"type": "map_action", "data": {"action": "highlight", "action_id": "6f1c1f9e-3b8a-4d0e-9a51-0c7f2f1d6a06", "feeder_ids": ["4A-12", "4A-13"], "substation_ids": [], "utility_id": "coned"}}

The tool_result frame that follows each call carries result.success and a result.message written for Eve, not for display. A client needs only the map_action frame.