Add support for interactive maps using Leaflet.js and update documentation

Author: nmaguiar

README.md

@@ -215,6 +215,7 @@ The tester includes automatic cleanup with shutdown handlers to properly close M
 - **Rate Limiting** - Built-in rate limiting for API usage control
 - **Metrics & Observability** - Comprehensive runtime metrics for monitoring and cost tracking
 - **Enhanced Visual Output** - UTF-8 box-drawing characters, ANSI color codes, and emoji for rich terminal displays (`useascii=true`)
+- **Interactive Maps** - Ask the agent to return Leaflet map snippets for geographic prompts, rendered directly in the console transcript and web UI (`usemaps=true`)
 
 ## Documentation
 
@@ -265,6 +266,7 @@ Mini-A ships with complementary components:
 | `chatbotmode` | Conversational assistant mode | `false` |
 | `useplanning` | Enable task planning workflow with validation and dynamic replanning | `false` |
 | `useascii` | Enable enhanced UTF-8/ANSI visual output with colors and emojis | `false` |
+| `usemaps` | Encourage Leaflet-based interactive map outputs for geographic data | `false` |
 | `mode` | Apply preset from `mini-a-modes.yaml` or `~/.openaf-mini-a_modes.yaml` | - |
 | `modelman` | Launch the interactive model definitions manager | `false` |
 | `maxsteps` | Maximum steps before forcing final answer | `15` |

USAGE.md

@@ -179,7 +179,7 @@ Set `OAF_MINI_A_MODE=<name>` to pick a default preset when you do not supply `mo
 - **`shellutils`** – Shell plus the Mini Utils Tool MCP utilities (`useutils=true usetools=true`).
 - **`chatbot`** – Lightweight conversational mode (`chatbotmode=true`).
 - **`web`** – Browser UI with tool registration (`usetools=true`).
-- **`webfull`** – Web UI with history, attachments, diagrams, charts, ASCII sketches, and planning enabled (`usetools=true usediagrams=true usecharts=true useascii=true usehistory=true useattach=true historykeep=true useplanning=true`).
+- **`webfull`** – Web UI with history, attachments, diagrams, charts, and ASCII sketches enabled (`usetools=true usediagrams=true usecharts=true useascii=true usehistory=true useattach=true historykeep=true useplanning=true`). Add `usemaps=true` if you also want interactive map guidance in this preset.
 
 ### Creating Custom Presets
 
@@ -254,7 +254,7 @@ Optional flags when starting the server:
 
 - `showexecs=true` to show executed commands in the interaction stream
 - `logpromptheaders=origin,referer` to log selected incoming headers for debugging
-- `usediagrams=false` / `usecharts=false` / `useascii=false` to disable Mermaid, Chart.js, or ASCII sketch guidance when running headless
+- `usediagrams=false` / `usecharts=false` / `useascii=false` / `usemaps=false` to disable Mermaid, Chart.js, ASCII sketch, or Leaflet map guidance when running headless
 - `usehistory=true` to expose the history side panel and persist conversations on disk
 - `historypath=/tmp/mini-a-history` / `historyretention=600` / `historykeep=true` to manage history storage (see comments in `mini-a-web.yaml`)
 - `historys3bucket=my-bucket historys3prefix=sessions/` to mirror history JSON files to S3 (supports `historys3url`, `historys3accesskey`, `historys3secret`, `historys3region`, `historys3useversion1`, `historys3ignorecertcheck`). History is uploaded at optimized checkpoints: immediately after user prompts and when final answers are provided, rather than on every interaction event
@@ -332,7 +332,7 @@ docker run -d --rm \
   -e OAF_MODEL="(type: openai, key: '...', url: 'https://api.groq.com/openai', model: openai/gpt-oss-20b, timeout: 900000, temperature: 0)" \
   -p 12345:12345 \
   openaf/oaf:edge \
-  onport=12345 usecharts=true usediagrams=true usetools=true mcpproxy=true
+  onport=12345 usecharts=true usediagrams=true usemaps=true usetools=true mcpproxy=true
 ```
 
 **Web interface with history and attachments:**
@@ -346,7 +346,7 @@ docker run -d --rm \
   openaf/oaf:edge \
   onport=12345 chatbotmode=true \
   usehistory=true historykeep=true historypath=/tmp/history \
-  useattach=true usediagrams=true usecharts=true
+  useattach=true usediagrams=true usecharts=true usemaps=true
 ```
 
 #### Pattern 3: Goal-Based Execution
@@ -590,6 +590,7 @@ Only when every stage returns an empty list (or errors) does Mini-A log the issu
   - **ANSI color codes**: Semantic highlighting for errors (red), success (green), warnings (yellow), info (blue/cyan), with support for bold, underline, backgrounds, and combined styles. Colors are applied outside markdown code blocks for proper terminal rendering
   - **Markdown tables**: Preferred format for tabular data with colored cell content for enhanced readability
   - **Progress indicators**: Block characters (█▓▒░), fractions (▏▎▍▌▋▊▉), spinners (⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏), and percentage displays with color gradients
+- **`usemaps`** (boolean, default: false): Prime the model to emit ```leaflet``` blocks that describe interactive maps (center coordinates, zoom, markers, layers). The console transcript preserves the fenced JSON, and the web UI auto-renders the configuration with Leaflet tiles, themed popups, and transparent markers.
 
 #### Libraries and Extensions
 - **`libs`** (string): Comma-separated list of additional OpenAF libraries to load
@@ -607,7 +608,7 @@ Only when every stage returns an empty list (or errors) does Mini-A log the issu
   - `shellutils` – Adds the Mini File Tool helpers as an MCP (`useutils=true usetools=true`) exposing `init`, `filesystemQuery`, and `filesystemModify` actions.
   - `chatbot` – Switches to conversational mode (`chatbotmode=true`).
   - `web` – Optimizes for the browser UI with MCP tools registered (`usetools=true`).
-  - `webfull` – Turns on diagrams, charts, ASCII sketches, attachments, history retention, and planning for the web UI (`usetools=true usediagrams=true usecharts=true useascii=true usehistory=true useattach=true historykeep=true useplanning=true`).
+  - `webfull` – Turns on diagrams, charts, ASCII sketches, attachments, history retention, and planning for the web UI (`usetools=true usediagrams=true usecharts=true useascii=true usehistory=true useattach=true historykeep=true useplanning=true`). Add `usemaps=true` when you also want interactive maps baked into this preset.
 
 Extend or override these presets by editing the YAML file—Mini-A reloads it on each run.
 

mini-a-modes.yaml

@@ -83,6 +83,7 @@ modes:
     params     :
       usediagrams: true
       usecharts  : true
+      usemaps    : true
       useascii   : false
       usetools   : true
       usehistory : true

mini-a.js

@@ -469,17 +469,19 @@ MiniA.buildVisualKnowledge = function(options) {
   var useDiagrams = _$(toBoolean(options.useDiagrams), "options.useDiagrams").isBoolean().default(false)
   var useCharts = _$(toBoolean(options.useCharts), "options.useCharts").isBoolean().default(false)
   var useAscii = _$(toBoolean(options.useAscii), "options.useAscii").isBoolean().default(false)
+  var useMaps = _$(toBoolean(options.useMaps), "options.useMaps").isBoolean().default(false)
 
-  if (!useDiagrams && !useCharts && !useAscii) return ""
+  if (!useDiagrams && !useCharts && !useAscii && !useMaps) return ""
 
   var existingKnowledge = isString(options.existingKnowledge) ? options.existingKnowledge : ""
   // Check if visual guidance already exists AND matches current flags
   if (existingKnowledge.indexOf("Visual output guidance (concise):") >= 0) {
     var hasDiagrams = existingKnowledge.indexOf("Diagrams:") >= 0
     var hasCharts = existingKnowledge.indexOf("Charts (strict format):") >= 0
     var hasAscii = existingKnowledge.indexOf("ASCII/UTF-8 visuals") >= 0
+    var hasMaps = existingKnowledge.indexOf("Interactive Maps:") >= 0
     // Only return early if existing guidance matches current flags
-    if (useDiagrams === hasDiagrams && useCharts === hasCharts && useAscii === hasAscii) {
+    if (useDiagrams === hasDiagrams && useCharts === hasCharts && useAscii === hasAscii && useMaps === hasMaps) {
       return ""
     }
   }
@@ -490,7 +492,7 @@ MiniA.buildVisualKnowledge = function(options) {
     "Visual output guidance (concise):\n\n" +
     "- Default to including a diagram, chart, or UTF-8/ANSI visual whenever structure, flow, hierarchy, metrics, or comparisons are involved.\n" +
     "- Always pair the visual with a short caption (1-2 sentences) summarizing the insight.\n" +
-    "- In your explanatory text and captions, refer only to the visual type (e.g., 'diagram', 'chart', 'table') without mentioning the technical implementation (Mermaid, Chart.js, ANSI codes, etc.)."
+    "- In your explanatory text and captions, refer only to the visual type (e.g., 'diagram', 'chart', 'table', 'map') without mentioning the technical implementation (Mermaid, Chart.js, Leaflet, ANSI codes, etc.)."
   )
 
   if (useDiagrams) {
@@ -579,6 +581,45 @@ MiniA.buildVisualKnowledge = function(options) {
     )
   }
 
+  if (useMaps) {
+    visualParts.push(
+      "Interactive Maps:\n" +
+      "  - Use ```leaflet``` fences to define interactive maps with Leaflet.js (v1.9.4).\n" +
+      "  - Provide map configuration as JSON with the following structure:\n" +
+      "    • center: [lat, lon] - Map center coordinates (required)\n" +
+      "    • zoom: number - Initial zoom level 1-18 (required, default: 13)\n" +
+      "    • markers: array of {lat, lon, popup?, icon?} - Points of interest (optional)\n" +
+      "    • layers: array of layer definitions (optional)\n" +
+      "    • options: {scrollWheelZoom?, dragging?, etc.} - Map interaction options (optional)\n" +
+      "  - Available marker icon types: 'default', 'red', 'green', 'blue', 'orange', 'yellow', 'violet', 'grey', 'black'\n" +
+      "  - Supported layer types:\n" +
+      "    • circle: {type: 'circle', center: [lat, lon], radius: meters, color?, fillColor?, fillOpacity?}\n" +
+      "    • polyline: {type: 'polyline', points: [[lat, lon], ...], color?, weight?}\n" +
+      "    • polygon: {type: 'polygon', points: [[lat, lon], ...], color?, fillColor?, fillOpacity?}\n" +
+      "    • rectangle: {type: 'rectangle', bounds: [[lat1, lon1], [lat2, lon2]], color?, fillColor?}\n" +
+      "  - Example configuration:\n" +
+      "    ```leaflet\n" +
+      "    {\n" +
+      "      \"center\": [51.505, -0.09],\n" +
+      "      \"zoom\": 13,\n" +
+      "      \"markers\": [\n" +
+      "        {\"lat\": 51.5, \"lon\": -0.09, \"popup\": \"London\", \"icon\": \"red\"},\n" +
+      "        {\"lat\": 51.51, \"lon\": -0.1, \"popup\": \"Nearby location\"}\n" +
+      "      ],\n" +
+      "      \"layers\": [\n" +
+      "        {\"type\": \"circle\", \"center\": [51.508, -0.11], \"radius\": 500, \"color\": \"red\", \"fillOpacity\": 0.3}\n" +
+      "      ]\n" +
+      "    }\n" +
+      "    ```\n" +
+      "  - CRITICAL RULES:\n" +
+      "    • Coordinates must be in [latitude, longitude] format with valid ranges: lat [-90, 90], lon [-180, 180]\n" +
+      "    • Use only static configuration values (no functions or callbacks)\n" +
+      "    • Provide complete data inline (no external fetching)\n" +
+      "    • Keep JSON valid and properly formatted\n" +
+      "  - Use maps for: geographic data, location visualization, spatial relationships, route planning, regional analysis, facility locations, coverage areas"
+    )
+  }
+
   var checklist = "\n\nVisual selection checklist:"
   var nextIndex = 1
   if (useDiagrams) {
@@ -603,6 +644,12 @@ MiniA.buildVisualKnowledge = function(options) {
     checklist += "\n" + nextIndex + ". When visuals are optional but helpful -> ANSI-enhanced ASCII table or emoticon map as fallback."
     nextIndex++
   }
+  if (useMaps) {
+    checklist += "\n" + nextIndex + ". Geographic data or locations -> interactive map with markers and layers."
+    nextIndex++
+    checklist += "\n" + nextIndex + ". Spatial relationships or coverage areas -> map with circles, polygons, or polylines."
+    nextIndex++
+  }
   checklist += "\n\nIf no visual type above applies to the user's request (e.g., purely narrative or conversational queries), you may provide text-only output without explanation."
 
   visualParts.push(checklist)
@@ -3668,7 +3715,7 @@ MiniA.prototype._handlePlanUpdate = function() {
 MiniA.prototype._cleanCodeBlocks = function(text) {
     if (!isString(text)) return text
     var trimmed = String(text).trim()
-    const isVisualBlock = trimmed.startsWith("```chart") || trimmed.startsWith("```mermaid");
+    const isVisualBlock = trimmed.startsWith("```chart") || trimmed.startsWith("```mermaid") || trimmed.startsWith("```leaflet");
     if (trimmed.startsWith("```") && trimmed.endsWith("```") && !isVisualBlock) {
         return trimmed.replace(/^```+[\w]*\n/, "").replace(/```+$/, "").trim()
     }
@@ -3957,8 +4004,8 @@ MiniA.prototype._processFinalAnswer = function(answer, args) {
     if (codeBlockMatch) {
       var lang = (codeBlockMatch[1] || "").toLowerCase()
       var body = codeBlockMatch[2]
-      // Preserve fences for visual languages like chart/chartjs and mermaid so the UI can render them
-      if (lang === "chart" || lang === "chartjs" || lang === "chart.js" || lang === "mermaid") {
+      // Preserve fences for visual languages like chart/chartjs, mermaid, and leaflet so the UI can render them
+      if (lang === "chart" || lang === "chartjs" || lang === "chart.js" || lang === "mermaid" || lang === "leaflet") {
         // keep original fenced block
         answer = trimmed
       } else {
@@ -6676,6 +6723,7 @@ MiniA.prototype.init = function(args) {
     args.usediagrams = _$(toBoolean(args.usediagrams), "args.usediagrams").isBoolean().default(false)
     args.usecharts = _$(toBoolean(args.usecharts), "args.usecharts").isBoolean().default(false)
     args.useascii = _$(toBoolean(args.useascii), "args.useascii").isBoolean().default(false)
+    args.usemaps = _$(toBoolean(args.usemaps), "args.usemaps").isBoolean().default(false)
     args.chatbotmode = _$(toBoolean(args.chatbotmode), "args.chatbotmode").isBoolean().default(args.chatbotmode)
     args.useplanning = _$(toBoolean(args.useplanning), "args.useplanning").isBoolean().default(args.useplanning)
     args.planmode = _$(toBoolean(args.planmode), "args.planmode").isBoolean().default(false)
@@ -6710,6 +6758,7 @@ MiniA.prototype.init = function(args) {
       useDiagrams: args.usediagrams,
       useCharts: args.usecharts,
       useAscii: args.useascii,
+      useMaps: args.usemaps,
       existingKnowledge: baseKnowledge
     })
     if (visualKnowledge.length > 0) {

mini-a.yaml

@@ -155,6 +155,11 @@ help:
     example  : "true"
     mandatory: false
     options  : ["true", "false"]
+  - name     : usemaps
+    desc     : Encourage Leaflet.js interactive maps by priming the agent with map guidance
+    example  : "true"
+    mandatory: false
+    options  : ["true", "false"]
   - name     : mcpdynamic
     desc     : Enable dynamic tool selection instead of registering all MCP tools (analyzes goal to select relevant tools)
     example  : "false"
@@ -339,6 +344,7 @@ jobs:
         usemermaid     : usemermaid
         usecharts      : usecharts
         useascii       : useascii
+        usemaps        : usemaps
         mcpdynamic     : mcpdynamic
         mcplazy        : mcplazy
         useplanning    : useplanning