echo6-docs/vault/projects/meshai.md

title	type	tags	aliases	related	updated
meshai	project	mesh	meshai MeshAI	meshcore-transport meshai-region-routing-plan meshai-prod-compose-override SESSION-HANDOFF-meshai-test meshai-config-hot-apply	2026-07-13

meshai

meshai is the LLM-powered LoRa-mesh assistant/gateway for the local Treasure/Magic Valley Meshtastic mesh — it ingests real-world event feeds and broadcasts concise alerts, and answers interactive LLM queries from mesh users (see services; MeshCore dual-transport design in meshcore-transport).

What it is

meshai (bot name AIDA) attaches to the mesh as a physical node and does two jobs at once:

• Outbound alerts. It consumes real-world situational-awareness feeds (weather, wildfire, traffic/511, space weather, earthquakes, water, satellite passes, …), normalizes them into events, and broadcasts short, chunked alerts to the mesh.
• Interactive assistant. Mesh users message it directly and get data-driven LLM answers over LoRa — mesh-health questions ("how's the mesh?"), knowledge/weather queries, and command handlers (!health, !region, !neighbors, !fires, !quakes, !space, !water, subscriptions, etc.).

The LLM backend is gemini-3.1-flash-lite with Google Search grounding (multi-backend capable — Gemini / OpenAI / Anthropic / local via LiteLLM). Conversation memory is a rolling window persisted to SQLite.

Where it runs

• Host: utility, CT 108 — 192.168.1.144 / Tailscale 100.64.0.32.
• Runtime: Docker, image work-meshai (local build, not ghcr.io/zvx-echo6/meshai:latest). Working tree + compose live in /home/zvx/meshai/work/.
• Ports: 8080 — dashboard / web API (/api/status); 7682 — config TUI (ttyd, meshai --config).
• Liveness: container healthcheck is a PID-file liveness probe (/tmp/meshai.pid), not an HTTP endpoint.
• Mesh link: connects over IP to MeshMonitor's virtual-node (vnode) service, which fronts the actual Meshtastic radio (a meshtasticd node — ultimately AIDA-N2 / channel 8 on aida-nebra). Everything is over the network; there is no radio physically attached to the meshai host. meshai can also connect directly to a meshtasticd over TCP, but the deployed configuration routes over IP/TCP to MeshMonitor's virtual node.
• Source: GitHub origin = zvx-echo6/meshai. Deploy = git pull + docker compose build && up -d (survives reboot).
• Distinct from the central service (utility CT 104) — meshai is a consumer of central's feed, not Central itself.

Architecture

The pipeline is feeds → events → notifications → mesh, plus a separate inbound interactive path.

• Central consumer (meshai/central/). CentralConsumer (consumer.py) subscribes to central's NATS JetStream firehose and hands each event to a per-adapter handler that normalizes it into a meshai event. Real handlers present:
  • nws_handler — NWS weather alerts
  • wfigs_handler — WFIGS wildfire perimeters/incidents
  • firms_handler — NASA FIRMS satellite fire hotspots
  • incident_handler — traffic incidents / Idaho 511
  • swpc_handler — SWPC space weather
  • quake_handler — earthquakes
  • avy_handler — avalanche advisories
  • nwis_handler (+ idaho_gauge_sites) — USGS NWIS stream gauges / hydro
  • satpass_handler (+ pass_predictor, tle_handler) — satellite pass prediction from TLEs
• Notifications pipeline (meshai/notifications/). Events flow through a bus/dispatcher with grouping, digesting, inhibition, pacing, scheduling and toggle filtering (pipeline/), then a composer → renderers → channels. The mesh renderer (renderers/mesh.py) does the (k/N) chunking that fits an alert into LoRa-sized packets; other renderers cover email/webhook.
• Transport (outbound). MeshConnector (connector.py) wraps the meshtastic package (serial/TCP, no BLE) and broadcasts to the mesh channel. Message-size assumptions are currently duplicated across several sites — the consolidation to a single transport.max_chars is part of meshcore-transport.
• Inbound / interactive. meshtastic pubsub → MessageRouter (router.py) builds a MeshMessage, routes commands/LLM queries → the LLM → Responder (responder.py) sends the reply back over the same connector.
• Network awareness. meshai pulls a live picture of the mesh from MeshView and MeshMonitor (mesh_sources.py, meshmonitor.py, mesh_health.py, mesh_data_store.py) to feed the LLM situational context and compute a 5-pillar mesh-health score.

Active / planned work

• meshcore-transport — proposed dual Meshtastic + meshcore-transport (send/receive on both meshes simultaneously; uniform message sizing to the smaller radio budget). Design agreed; open on hardware, the meshcore dependency, and branch timing.
• NWS severity normalization — CAP-severity pre-filter removed; NWS breadth is now governed solely by the dashboard Weather toggle threshold (warnings broadcast immediately).
• Fire-path correctness — WFIGS/FIRMS fire correlation and drain/pacer spam controls on the fire feed.