feat: add display_map tool for point maps on OpenStreetMap by tckaros · Pull Request #1206 · getnao/nao

tckaros · 2026-07-16T21:10:56Z

What

A new display_map agent tool that plots geographic point data from execute_sql results on an interactive MapLibre GL map, using OpenFreeMap (OSM-based vector tiles) as the default basemap.

This is the proof of concept behind #1205 — it's fully working, but it's mainly here to make that discussion concrete. If maps are a direction you want, I fully expect remarks on the approach and I'm happy to rework it.

How it works

Shared schema (apps/shared/src/tools/display-map.ts): query_id reference, lat/lng column keys, optional popup label_key/tooltip_keys, map_type enum ready for a future heatmap mode.
Shared geo logic (apps/shared/src/map-points.ts): one implementation used by both backend validation and frontend rendering — case-insensitive column resolution (exact match first), rejection of null/blank coordinates before Number() coercion (no fabricated (0,0) points), Web Mercator latitude limit, antimeridian-aware bounds.
Backend tool: resolves the query_id via getQueryResult (current run, then persisted chat history) and returns actionable errors (missing query, unresolvable column, no plottable rows) so the model is never told a map displayed when the UI can't render one. On success it reports plotted/dropped counts and warns about unresolvable popup keys or results over the render cap, so the model can self-correct its SQL.
Frontend: mirrors display_chart (same source-query resolution, now factored into a shared useSourceQuery hook used by both). MapLibre loads as a lazy chunk; popups are built with textContent only so query values can't inject HTML; rendering is capped at 5,000 points with a "showing first N" note; WebGL-unavailable clients get a graceful fallback instead of a crash.
Non-web surfaces: Slack/Teams/Telegram can't render an interactive map, so a completed display_map degrades to a "View interactive map in nao" link card. Automations, the MCP ask_nao sub-agent and WhatsApp exclude the tool entirely (WEB_CHAT_ONLY_TOOLS + a new getTools excludeBuiltinTools option), and the system prompt only advertises the tool when the run's tool set includes it.

Tests

apps/shared/tests/map-points.test.ts — coordinate validation, key resolution, wrapped bounds (16 tests)
apps/backend/tests/display-map-tool.test.ts — tool validation paths incl. history fallback (13 tests)
apps/backend/tests/agent-tools.test.ts + system-prompt gating tests

Known limitations / follow-ups

Basemap is a third-party service (tiles.openfreemap.org) and the VITE_MAP_STYLE_URL override is build-time only — see [feature] Map visualization for latitude/longitude query results #1205 for the configurability question.
Map colors and basemap style are snapshotted on mount (light/dark toggle needs a remount) — TODO in code.
No static PNG rendering for Slack/Teams/email yet (charts have one via generate-chart); WhatsApp link card TODO.
Polar data beyond ±85.05° is dropped (Web Mercator); globe projection would be the real answer.

🤖 Generated with Claude Code

github-actions · 2026-07-16T21:16:31Z

🧹 Preview Removed

The preview deployment for this PR has been cleaned up.

cubic-dev-ai

All reported issues were addressed

_{Reply with feedback, questions, or to request a fix.

Re-trigger cubic}

Bl3f · 2026-07-20T09:03:06Z

Hello @tckaros I really really like this idea and this is something we should add in nao either with this PR or in another form so lets move it forward.

2 things to have in mind I think before the review:

we already have a PR opened that we can expect to merge this week to support "vibe-coded chart" ; which is a system of plugins so as admins you could define a set of viz that you want your users to be able to use (cf. feat: custom chart plugins ("vibe coded charts") #945) — so really customs maps could fall into this
tho, i think we should have by default a scatterplot map at least and a choropleth, for this the main question for me is: should we give the agent a display_map tool or should we consider maps like charts and include this in display_chart tool

Happy to hear your thoughts!

socallmebertille

Hi, thanks a lot for this awesome contribution ! 👍💯

On top of your work, I added for now :

the WhatsApp integration (just a link that redirects the user to see the map in the chat UI)
the dark mode theme handling (and align the design to the rest of the app)

cubic-dev-ai

All reported issues were addressed across 36 files

_{Reply with feedback, questions, or to request a fix.

Re-trigger cubic}

Adds a new display_map agent tool that renders geographic point data from execute_sql results on an interactive MapLibre GL map, using OpenFreeMap (OSM-based vector tiles) as the default basemap, overridable via VITE_MAP_STYLE_URL. - Shared zod schema with query_id reference, lat/lng column keys and optional popup label/tooltip keys; map_type enum ready for a future heatmap mode - Point building/validation lives in @nao/shared (map-points.ts): column keys resolve exact-first then case-insensitively (resolveColumnName, with resolveDataKey moved to shared on top of it), rows with null or blank coordinates are rejected before Number() coercion so no fabricated (0,0) points are plotted, latitudes beyond the Web Mercator limit (85.051129°) are dropped instead of collapsing onto the map edge, and keys resolving to the same column are rejected instead of silently plotting lat=lng - The tool resolves the query_id through getQueryResult (current run, then persisted chat history) and fails with an actionable error when the query is missing, a column does not resolve, or no row carries plottable coordinates; on success it reports plotted and dropped row counts so the model can notice partial data and fix its SQL - Frontend component mirrors display_chart: resolves rows from the sibling execute_sql message part; MapLibre loads in a lazy chunk so the main bundle is unaffected; kept out of collapsed tool groups like charts; rendering is capped at 5000 points with a "showing first N" note - fitBounds wraps across the antimeridian (computeMapBounds), so points at 179°E/179°W fit a 2° span instead of a world-scale view - Popups are built with textContent only so query values cannot inject HTML - Slack, Teams and Telegram cannot render an interactive map, so a completed display_map degrades to a "View interactive map in nao" link card; automations, the MCP ask_nao sub-agent and WhatsApp exclude the tool (shared WEB_CHAT_ONLY_TOOLS list, getTools excludeBuiltinTools option) and the system prompt only advertises the tool when the run's tool set includes it Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

tckaros · 2026-07-24T06:04:53Z

Hello @tckaros I really really like this idea and this is something we should add in nao either with this PR or in another form so lets move it forward.

2 things to have in mind I think before the review:

we already have a PR opened that we can expect to merge this week to support "vibe-coded chart" ; which is a system of plugins so as admins you could define a set of viz that you want your users to be able to use (cf. feat: custom chart plugins ("vibe coded charts") #945) — so really customs maps could fall into this

tho, i think we should have by default a scatterplot map at least and a choropleth, for this the main question for me is: should we give the agent a display_map tool or should we consider maps like charts and include this in display_chart tool

Happy to hear your thoughts!

Hi @Bl3f,

Thanks for your review!

I actually had similar questions on my side :)
I agree that both directions you mentioned make a lot of sense, but I haven't had the time to investigate them yet.

If I manage to run some tests, I'll share my feedback on which direction (or evolution) seems to make the most sense.

tckaros mentioned this pull request Jul 16, 2026

[feature] Map visualization for latitude/longitude query results #1205

Closed

tckaros force-pushed the feat/display-map-tool branch from 8cfda0a to 801f2e5 Compare July 16, 2026 21:21

cubic-dev-ai Bot reviewed Jul 16, 2026

View reviewed changes

Comment thread apps/backend/src/agents/tools/display-map.ts

Comment thread apps/backend/src/agents/tools/index.ts Outdated

tckaros force-pushed the feat/display-map-tool branch from 801f2e5 to 65a79d5 Compare July 16, 2026 21:37

Bl3f assigned socallmebertille Jul 22, 2026

socallmebertille force-pushed the feat/display-map-tool branch from 65a79d5 to 2ed8ab6 Compare July 23, 2026 13:09

socallmebertille reviewed Jul 23, 2026

View reviewed changes

socallmebertille force-pushed the feat/display-map-tool branch from 2ed8ab6 to 1072219 Compare July 23, 2026 13:32

socallmebertille approved these changes Jul 23, 2026

View reviewed changes

cubic-dev-ai Bot reviewed Jul 23, 2026

View reviewed changes

Comment thread apps/backend/src/services/telegram.ts Outdated

Comment thread apps/backend/src/services/agent.ts Outdated

tckaros and others added 2 commits July 23, 2026 15:50

add theme handler + include display_map tool in whatsapp

d410b38

socallmebertille force-pushed the feat/display-map-tool branch from 56613c7 to d410b38 Compare July 23, 2026 13:52

socallmebertille added 2 commits July 23, 2026 15:54

fix from cubic review

7956732

chore: sync package-lock with maplibre-gl dependency

4742e36

Bl3f merged commit cf594c6 into getnao:main Jul 23, 2026
4 of 5 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add display_map tool for point maps on OpenStreetMap#1206

feat: add display_map tool for point maps on OpenStreetMap#1206
Bl3f merged 4 commits into
getnao:mainfrom
tckaros:feat/display-map-tool

tckaros commented Jul 16, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 16, 2026 •

edited

Loading

Uh oh!

cubic-dev-ai Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Bl3f commented Jul 20, 2026

Uh oh!

socallmebertille left a comment

Uh oh!

cubic-dev-ai Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tckaros commented Jul 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

tckaros commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

How it works

Tests

Known limitations / follow-ups

Uh oh!

github-actions Bot commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🧹 Preview Removed

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Bl3f commented Jul 20, 2026

Uh oh!

socallmebertille left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tckaros commented Jul 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tckaros commented Jul 16, 2026 •

edited

Loading

github-actions Bot commented Jul 16, 2026 •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading