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.
- **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.
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:
-`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.
- [[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.
