matt/meshai
1
0
Fork 0
mirror of https://github.com/zvx-echo6/meshai.git synced 2026-05-21 15:14:45 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs: Complete README rewrite — mesh intelligence, data sources, updated architecture

Browse source
This commit is contained in:
MeshAI Claude 2026-05-06 01:28:59 +00:00
commit d5fc69e9a0
1 changed files with 347 additions and 329 deletions
Download patch file Download diff file Expand all files Collapse all files

676
README.md
View file

@ -1,329 +1,347 @@
# MeshAI # MeshAI
LLM-powered assistant for Meshtastic mesh networks. LLM-powered mesh intelligence assistant for Meshtastic networks. MeshAI connects to your mesh as a physical node, monitors network health in real-time, and answers questions about your infrastructure over LoRa.
## Features ## What It Does
- **LLM Chat**: Responds to @mentions and DMs with AI-generated responses MeshAI runs on your Meshtastic node and provides:
- **Multi-backend**: Supports OpenAI, Anthropic Claude, Google Gemini, and local LLMs via LiteLLM
- **Knowledge Base (RAG)**: Hybrid FTS5 + vector search over Meshtastic documentation - **Mesh Intelligence** — 5-pillar health scoring, per-region breakdowns, infrastructure monitoring, coverage gap analysis, and environmental sensing
- **Message Chunking**: Sentence-aware splitting with continuation prompts for long responses - **Conversational Queries** — ask "how's the mesh?" or "tell me about MHR" and get data-driven answers over LoRa
- **Bang Commands**: `!help`, `!ping`, `!reset`, `!status`, `!weather` - **Node Distance** — GPS-based distance calculations between any two nodes on the mesh
- **Conversation History**: Per-user context maintained in SQLite - **Multi-Source Awareness** — aggregates data from multiple Meshview instances and MeshMonitor with staggered polling
- **Rate Limiting**: Configurable delays to avoid flooding the mesh - **Feeder Gateway Tracking** — identifies which physical MQTT gateways hear each node and signal quality
- **advBBS Compatible**: Runs alongside [advBBS](https://github.com/zvx-echo6/advbbs) on the same node — protocol sync messages and mail notifications are automatically filtered - **Subscriptions** — scheduled daily/weekly health reports and instant alerts delivered via DM
- **Rich Configurator**: Interactive TUI for easy setup - **LLM Chat** — general conversation, knowledge base lookups, and weather queries
- **MeshMonitor Integration**: Syncs with [MeshMonitor](https://github.com/Yeraze/meshmonitor) by Yeraze to avoid duplicate responses - **Multi-Backend** — supports Google Gemini, OpenAI, Anthropic Claude, and local LLMs via LiteLLM
## Installation ## Quick Start
```bash ```bash
# Clone the repository # Clone
git clone https://github.com/zvx-echo6/meshai.git git clone https://github.com/zvx-echo6/meshai.git
cd meshai cd meshai
# Install with pip # Install
pip install -e . pip install -e .
# Or install dependencies manually # Configure (interactive TUI)
pip install -r requirements.txt meshai --config
```
# Run
## Quick Start meshai
```
```bash
# Run the configurator Or with Docker:
meshai --config
```bash
# Or copy and edit the example config mkdir -p meshai/data && cd meshai
cp config.example.yaml config.yaml curl -O https://raw.githubusercontent.com/zvx-echo6/meshai/main/docker-compose.yml
# Edit config.yaml with your settings curl -o data/config.yaml https://raw.githubusercontent.com/zvx-echo6/meshai/main/config.example.yaml
# Edit data/config.yaml
# Run the bot docker compose up -d
meshai ```
```
## Commands
## Configuration
| Command | Description |
Run `meshai --config` to launch the interactive configurator, or edit `config.yaml` directly. |---------|-------------|
| `!health` | Mesh health overview with colored status dots |
### Key Settings | `!region` | List all regions with health status |
| `!region [name]` | Detailed region breakdown |
```yaml | `!neighbors [node]` | Top infrastructure neighbors with signal quality |
bot: | `!sub daily 6pm` | Subscribe to daily health reports |
name: "ai" # @mention trigger | `!sub weekly 8am sun` | Subscribe to weekly digest |
respond_to_mentions: true | `!sub alerts` | Subscribe to instant alerts on issues |
respond_to_dms: true | `!unsub [type]` | Remove a subscription |
| `!mysubs` | List your active subscriptions |
connection: | `!clear` | Clear conversation history |
type: "serial" # serial or tcp | `!help` | Show available commands |
serial_port: "/dev/ttyUSB0" | `!help [cmd]` | Detailed help for a command |
llm: Commands can be disabled in config if another service (like MeshMonitor) handles them.
backend: "openai" # openai, anthropic, google
api_key: "your-api-key" ## Mesh Intelligence
model: "gpt-4o-mini"
``` MeshAI continuously polls mesh data sources and computes a 5-pillar health score:
### Using Local LLMs | Pillar | Weight | What It Measures |
|--------|--------|------------------|
MeshAI works with any OpenAI-compatible API, including: | Infrastructure | 30% | Router uptime — how many infra nodes are online |
| Utilization | 25% | Channel busyness — RF congestion across the mesh |
- **LiteLLM**: `base_url: "http://localhost:4000/v1"` | Coverage | 20% | Gateway reach — how many monitoring sources see each node |
- **Open WebUI**: `base_url: "http://localhost:3000/api"` | Behavior | 15% | Traffic patterns — detecting noisy or misconfigured nodes |
- **Ollama**: `base_url: "http://localhost:11434/v1"` | Power | 10% | Battery health — infrastructure nodes only |
## Commands ### Health Display
| Command | Description | `!health` shows a compact overview with personality:
|---------|-------------|
| `!help` | Show available commands | ```
| `!ping` | Test connectivity | 📡 Mesh 🟢 healthy
| `!reset` | Clear your conversation history | 🏗️ 15/16 routers up
| `!status` | Show bot status and stats | ❌ Down: TVM Tablerock Relay
| `!weather [location]` | Get weather (uses GPS if no location given) | 📶 152 full coverage, 94 on thin ice
🔥 Hayden Peak Router at 21% util
## Usage Examples 🔋 All infra powered ✅
🌡️ 29-34°C across 2 sensors
**Chat via @mention:** Treasure Valley 🟢 | Magic Valley 🟢
``` ```
@ai What's the weather like today?
> Seattle: 52F, Partly Cloudy, Wind 8mph Status dots: 🔵 perfect (100) · 🟢 healthy (75+) · 🟠 warning (50+) · 🔴 critical (<50)
```
### Monitoring Rules
**Direct message:**
``` Infrastructure nodes (routers, repeaters) are monitored individually with full detail — battery, offline alerts, coverage, neighbors, hardware. Client nodes dying is normal and not tracked. Channel utilization and environmental sensors are monitored for all nodes.
DM: Tell me a short joke
> Why don't scientists trust atoms? They make up everything! ### Conversational Queries
```
Ask questions naturally over LoRa:
**Weather command:**
``` - "how's the mesh?" → health overview with top issues
!weather Portland - "tell me about MHR" → full node detail with neighbors, coverage, feeders
> Portland: 48F, Rain, Wind 12mph - "where do we need more coverage?" → named gaps with specific nodes
``` - "how far is MHR from AIDA?" → GPS distance calculation
- "which nodes only reach one gateway?" → named nodes with their gateway
## Architecture - "which gateway has the best signal?" → feeder comparison
``` ### Geographic Regions
┌──────────────────────────────────────────────────────────────────┐
│ MeshAI │ Regions are configurable with local names, descriptions, aliases, and cities — all manageable through the TUI. No hardcoded geography in the code.
├──────────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌──────────────────────┐ │ ```yaml
│ │ Meshtastic │ │ Message │ │ LLM Backend │ │ mesh_intelligence:
│ │ Connector │───▶│ Router │───▶│ (pluggable) │ │ regions:
│ │ Serial/TCP │ │ │ │ │ │ - name: "South Central ID"
│ └─────────────┘ └──────┬──────┘ └──────────────────────┘ │ local_name: "Magic Valley"
│ │ │ │ │ description: "Twin Falls area"
│ │ ┌──────▼──────┐ │ │ aliases: ["southern Idaho", "magic valley"]
│ │ │ Conversation│ │ │ cities: ["Twin Falls", "Burley", "Jerome"]
│ │ │ History │◀─────────────┘ │ lat: 42.5
│ │ │ (SQLite) │ │ lon: -114.5
│ │ └─────────────┘ │ radius_km: 80
│ │ │ │ ```
│ │ ┌──────▼──────┐ ┌──────────────────────┐ │
│ │ │ Knowledge │───▶│ Hybrid FTS5+Vector │ │ ## Data Sources
│ │ │ Base │ │ (sqlite-vec + BGE) │ │
│ │ └─────────────┘ └──────────────────────┘ │ MeshAI aggregates from multiple sources using staggered tick-based polling (one API call per 30-second tick):
│ │ │
│ ▼ │ ### Meshview
│ ┌─────────────┐ ┌─────────────┐ │
│ │ Responder │───▶│ Chunker │ Sentence-aware splitting │ Unauthenticated REST API. Supports multiple instances.
│ │ │ │ │ + continuation prompts │
│ └─────────────┘ └─────────────┘ │ | Endpoint | Interval | Data |
└──────────────────────────────────────────────────────────────────┘ |----------|----------|------|
``` | `/api/packets` | 30s | Near real-time packet feed |
| `/api/nodes` | 2 min | Node list with metadata |
## Knowledge Base (RAG) | `/api/stats` | 3 min | Traffic statistics |
| `/api/edges` | 3 min | Node-to-node connections |
MeshAI can answer questions using a local knowledge base built from Meshtastic documentation. The system uses hybrid search combining: | `/api/traceroutes` | 5 min | Route data |
| `/api/packets_seen` | 10 min | Per-gateway RSSI/SNR (sampled) |
- **FTS5 keyword search** — fast exact term matching with domain-aware query construction
- **Vector embeddings** — semantic similarity using `bge-small-en-v1.5` (384 dimensions) ### MeshMonitor
- **Reciprocal Rank Fusion** — merges results from both methods for best relevance
Authenticated (Bearer token). Single instance.
**Building the knowledge base:**
| Endpoint | Interval | Data |
```bash |----------|----------|------|
# Extract from Meshtastic ZIM file | `/api/v1/packets` | 60s | Packet feed |
python scripts/zim_to_knowledge.py meshtastic.zim --output knowledge.db | `/api/v1/nodes` | 2 min | Nodes with battery, utilization, hardware |
| `/api/v1/telemetry` | 2 min | Environmental sensors, device metrics |
# Or from markdown files | `/api/v1/traceroutes` | 5 min | Route data |
python scripts/md_to_knowledge.py docs/ --output knowledge.db | `/api/v1/channels` | 5 min | Channel configuration |
``` | `/api/v1/network` | 5 min | Network statistics |
| `/api/v1/solar` | 10 min | Solar estimates |
**Configuration:**
### Rate Limiting
```yaml
knowledge: Built-in protection for all sources: HTTP 429 backoff with Retry-After, exponential backoff on consecutive errors, slow response warnings, and optional polite mode for shared instances.
enabled: true
db_path: /data/meshai_knowledge.db ### Source Configuration
top_k: 5 # Number of chunks to retrieve
fts_weight: 0.5 # Weight for keyword matches (0-1) ```yaml
vector_weight: 0.5 # Weight for semantic matches (0-1) mesh_sources:
``` - name: "local-meshview"
type: meshview
The knowledge base requires `sqlite-vec` and `fastembed` (installed automatically with requirements.txt). url: "http://192.168.1.100:8080"
enabled: true
## Message Chunking
- name: "meshmonitor"
Long LLM responses are automatically split into mesh-friendly chunks: type: meshmonitor
url: "http://192.168.1.100:3333"
- **Sentence-aware** — never splits a sentence across messages api_token: "your-bearer-token"
- **Configurable limits** — max characters per message, max messages per response enabled: true
- **Continuation prompts** — if content remains, asks "Want me to keep going?" ```
- **Natural follow-ups** — responds to "yes", "ok", "continue", "more", etc.
## Knowledge Base (RAG)
**Configuration:**
MeshAI answers questions using a local knowledge base built from Meshtastic documentation. The system uses hybrid search combining FTS5 keyword search, vector embeddings via `bge-small-en-v1.5`, and Reciprocal Rank Fusion for best relevance.
```yaml
response: ```bash
max_length: 200 # Max chars per message # Build from Meshtastic ZIM file
max_messages: 3 # Messages before continuation prompt python scripts/zim_to_knowledge.py meshtastic.zim --output knowledge.db
```
# Or from markdown files
## Docker python scripts/md_to_knowledge.py docs/ --output knowledge.db
```
### Quick Start with Docker
```yaml
```bash knowledge:
# Create working directory enabled: true
mkdir -p meshai/data && cd meshai db_path: /data/meshai_knowledge.db
top_k: 5
# Download docker-compose file fts_weight: 0.5
curl -O https://raw.githubusercontent.com/zvx-echo6/meshai/main/docker-compose.yml vector_weight: 0.5
```
# Copy and edit config
curl -o data/config.yaml https://raw.githubusercontent.com/zvx-echo6/meshai/main/config.example.yaml Requires `sqlite-vec` and `fastembed` (installed with requirements.txt).
# Edit data/config.yaml with your settings
## Architecture
# Start
docker compose up -d ```
┌──────────────────────────────────────────────────────────────────────┐
# View logs │ MeshAI │
docker compose logs -f ├──────────────────────────────────────────────────────────────────────┤
``` │ │
│ DATA SOURCES INTELLIGENCE DELIVERY │
### Docker Configuration │ ┌─────────────┐ ┌──────────────┐ ┌────────────┐ │
│ │ Meshview ×N │─────┐ │ Health Engine │────────▶│ Reporter │ │
**TCP Connection** (recommended for Docker): │ │ (staggered) │ │ │ 5-pillar │ │ Tier 1/2 │ │
```yaml │ └─────────────┘ ▼ │ scoring │ └─────┬──────┘ │
# data/config.yaml │ ┌─────────────┐ ┌──────┴──┐ │ │ │ │
connection: │ │ MeshMonitor │─▶│ Data │─┘ │ ┌─────▼──────┐ │
type: "tcp" │ │ (staggered) │ │ Store │ │ │ Router │ │
tcp_host: "192.168.1.100" # Your Meshtastic node IP │ └─────────────┘ │ SQLite │ │ │ scope/dist │ │
tcp_port: 4403 │ └─────────┘ │ └─────┬──────┘ │
``` │ │ │ │ │
│ ┌────▼────┐ ┌─────▼──────┐ ┌────▼────┐ │
**Serial Connection**: │ │ Feeder │ │ LLM │ │ Chunker │ │
```yaml │ │ Sampling│ │ Backend │ │LoRa-fit │ │
# data/config.yaml │ └─────────┘ └────────────┘ └────┬────┘ │
connection: │ │ │
type: "serial" │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌────▼────┐ │
serial_port: "/dev/ttyUSB0" │ │ Knowledge │ │ Conversation│ │ Subscription │ │Responder│ │
``` │ │ Base (RAG) │ │ History │ │ Manager │ │ DM/CH │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────┘ │
Then edit `docker-compose.serial.yml` to match your device path. │ │
└──────────────────────────────────────────────────────────────────────┘
### Environment Variables ```
You can pass the API key via environment variable instead of config file: ## Message Chunking
```bash Long responses are split into mesh-friendly chunks with sentence-aware splitting, configurable limits, and continuation prompts. Command output (like `!health`) packs multiple lines into 2-3 messages using newlines within each message to minimize airtime usage.
LLM_API_KEY=your-key-here docker compose up -d
``` ```yaml
response:
Or create a `.env` file: max_length: 200 # Max chars per message
```bash max_messages: 3 # Messages before continuation prompt
LLM_API_KEY=your-key-here ```
```
## LLM Configuration
### View Logs
```yaml
```bash llm:
docker compose logs -f meshai backend: "google" # openai, anthropic, google
``` api_key: "your-api-key"
model: "gemini-2.0-flash"
## Running Alongside advBBS ```
MeshAI is designed to coexist with [advBBS](https://github.com/zvx-echo6/advbbs) on the same Meshtastic node. Both connect via TCP to meshtasticd and share the radio, but MeshAI automatically ignores advBBS traffic: ### Local LLMs
- **Sync protocol** — `MAILREQ|`, `MAILACK|`, `MAILDAT|`, `BOARDREQ|`, etc. MeshAI works with any OpenAI-compatible API:
- **RAP protocol** — `advBBS|` pings, pongs, and route advertisements
- **Mail notifications** — `[MAIL]` new message alerts - **LiteLLM**: `base_url: "http://localhost:4000/v1"`
- **Bang commands in DMs** — `!mail`, `!board`, etc. are left for advBBS to handle - **Open WebUI**: `base_url: "http://localhost:3000/api"`
- **Ollama**: `base_url: "http://localhost:11434/v1"`
No special configuration is needed. The filter is enabled by default and can be toggled in `config.yaml`:
## Docker
```yaml
bot: ### TCP Connection (recommended)
filter_bbs_protocols: true # set false to disable
``` ```yaml
connection:
Plain-text BBS responses (e.g. "Welcome back, matt!") are indistinguishable from normal user messages and will be processed normally — this is a known and accepted limitation. type: "tcp"
tcp_host: "192.168.1.100"
## MeshMonitor Integration tcp_port: 4403
```
MeshAI integrates with [MeshMonitor](https://github.com/Yeraze/meshmonitor), a comprehensive Meshtastic monitoring platform by Yeraze. When enabled, MeshAI automatically fetches MeshMonitor's auto-responder trigger patterns and ignores messages that MeshMonitor handles, preventing duplicate responses on the mesh.
### Serial Connection
**Features:**
- Automatic trigger discovery via MeshMonitor's HTTP API ```yaml
- Dynamic ignore list — no manual sync needed connection:
- Trigger list injected into the LLM prompt so MeshAI can discuss MeshMonitor commands conversationally type: "serial"
- Configurable via TUI (option 9) or config.yaml serial_port: "/dev/ttyUSB0"
```
**Configuration:**
Edit `docker-compose.serial.yml` to match your device path.
```yaml
meshmonitor: ### Environment Variables
enabled: true
url: "http://192.168.1.100:8080" ```bash
inject_into_prompt: true LLM_API_KEY=your-key-here docker compose up -d
refresh_interval: 300 ```
```
## Running Alongside Other Services
MeshMonitor is a separate project — get it at https://github.com/Yeraze/meshmonitor
### advBBS
## Running as a Service
MeshAI coexists with [advBBS](https://github.com/zvx-echo6/advbbs) on the same node. BBS protocol messages (sync, RAP, mail notifications) are automatically filtered. No configuration needed.
Create `/etc/systemd/system/meshai.service`:
```yaml
```ini bot:
[Unit] filter_bbs_protocols: true
Description=MeshAI - Meshtastic LLM Assistant ```
After=network.target
### MeshMonitor
[Service]
Type=simple MeshAI integrates with [MeshMonitor](https://github.com/Yeraze/meshmonitor) at two levels: it fetches MeshMonitor's auto-responder patterns to avoid duplicate responses, and it uses MeshMonitor's API as a data source for mesh intelligence (battery, telemetry, traceroutes, solar).
User=your-user
WorkingDirectory=/path/to/meshai ```yaml
ExecStart=/usr/bin/python3 -m meshai meshmonitor:
Restart=always enabled: true
RestartSec=10 url: "http://192.168.1.100:8080"
inject_into_prompt: true
[Install] refresh_interval: 300
WantedBy=multi-user.target ```
```
## Running as a Service
Then:
```bash ```ini
sudo systemctl daemon-reload # /etc/systemd/system/meshai.service
sudo systemctl enable meshai [Unit]
sudo systemctl start meshai Description=MeshAI - Meshtastic Mesh Intelligence
``` After=network.target
## Acknowledgments [Service]
Type=simple
- [Meshtastic](https://meshtastic.org/) — the mesh networking platform User=your-user
- [MeshMonitor](https://github.com/Yeraze/meshmonitor) by Yeraze — monitoring integration WorkingDirectory=/path/to/meshai
- [advBBS](https://github.com/zvx-echo6/advbbs) — BBS coexistence design ExecStart=/usr/bin/python3 -m meshai
- [sqlite-vec](https://github.com/asg017/sqlite-vec) by Alex Garcia — vector search in SQLite Restart=always
- [fastembed](https://github.com/qdrant/fastembed) by Qdrant — fast local embeddings RestartSec=10
## License [Install]
WantedBy=multi-user.target
MIT License ```
## Author ```bash
sudo systemctl daemon-reload
K7ZVX - matt@echo6.co sudo systemctl enable meshai
sudo systemctl start meshai
```
## Acknowledgments
- [Meshtastic](https://meshtastic.org/) — the mesh networking platform
- [MeshMonitor](https://github.com/Yeraze/meshmonitor) by Yeraze — monitoring integration and data source
- [advBBS](https://github.com/zvx-echo6/advbbs) — BBS coexistence design
- [sqlite-vec](https://github.com/asg017/sqlite-vec) by Alex Garcia — vector search in SQLite
- [fastembed](https://github.com/qdrant/fastembed) by Qdrant — fast local embeddings
## License
MIT License
## Author
K7ZVX - matt@echo6.co