lorabot/README.md

lorabot

Bridges a MeshCore companion radio to any OpenAI-compatible LLM endpoint (e.g. llama-server, vLLM, Ollama). Listens for direct messages on the device, runs each conversation through the LLM with full per-sender history stored in SQLite, and replies back over the mesh — trimmed to the MeshCore packet payload limit.

Quick start

python -m venv .venv && source .venv/bin/activate
pip install -e .

cp config.example.toml config.toml
# edit serial_port and [llm] in config.toml

python -m lorabot

Config file path defaults to ./config.toml and can be overridden with LORABOT_CONFIG. Any field can be overridden via env vars, e.g. LORABOT_LLM__API_KEY=sk-....

Layout

• src/lorabot/bot.py — connect, subscribe to CONTACT_MSG_RECV, dispatch each DM.
• src/lorabot/db.py — SQLite schema and per-conversation repo functions.
• src/lorabot/llm.py — AsyncOpenAI wrapper.
• src/lorabot/messages.py — UTF-8-safe byte-length trimming.
• src/lorabot/config.py — TOML + env-var settings (pydantic-settings).

Docker

Build and push a multi-arch image (linux/amd64 + linux/arm64):

docker login registry.example.com                    # once
export LORABOT_IMAGE=registry.example.com/team/lorabot
./scripts/build-and-push.sh                          # tags: latest + <git sha>
EXTRA_TAGS="v0.1.0" ./scripts/build-and-push.sh      # add explicit version
PUSH=0 PLATFORMS=linux/amd64 ./scripts/build-and-push.sh   # local load only

Run via compose (set LORABOT_IMAGE, LORABOT_LLM_BASE_URL, LORABOT_LLM_MODEL, optionally LORABOT_DEVICE):

export LORABOT_IMAGE=registry.example.com/team/lorabot:latest
export LORABOT_LLM_BASE_URL=http://llama:8080/v1
export LORABOT_LLM_MODEL=llama-3.1-8b-instruct
export LORABOT_DEVICE=/dev/ttyUSB0
docker compose up -d

The container expects config.toml mounted at /etc/lorabot/config.toml and persists SQLite to a named volume at /data. Any field can still be overridden via LORABOT_<SECTION>__<KEY> env vars.