echo6-docs/vault/projects/meshai.md

---
title: meshai
type: project
tags:
  - mesh
  - ai
aliases:
  - meshai
  - MeshAI
related:
  - [[services]]
  - [[meshcore-transport]]
  - [[central]]
updated: 2026-07-11
---

# 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.