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": "…", …}}
| Field | Type | Meaning |
|---|---|---|
type | "map_action" | The frame type. |
data.action | "focus" | "select" | "layers" | "highlight" | Which change to make. |
data.action_id | string (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.
| Field | Type | Meaning |
|---|---|---|
region | string | A 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.
| Field | Type | Meaning |
|---|---|---|
utility_id | string | Always present. The utility id /api/gridbase/v1 returns, for example coned. |
substation_id | string | Optional. 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.
| Field | Type | Meaning |
|---|---|---|
layers | object | Layer 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.
| Field | Type | Meaning |
|---|---|---|
feeder_ids | string[] | Feeder ids, as query_hosting_capacity returns them. Always present, possibly empty. |
substation_ids | string[] | Substation ids, as for select. Always present, possibly empty. |
utility_id | string | Optional. 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.