home-services/discord-bot/README.md

discord-bot

discord-bot is a Discord slash-command service for home control. It calls ha-gateway for direct Home Assistant actions and ai-gateway for free-form AI-assisted commands.

Runtime Flow

1. The process loads .env, opens a Discord session, and registers slash commands.
2. A user runs a command such as /light list, /light on, or /ai query.
3. The Discord adapter validates and routes the interaction to the app layer.
4. The app layer calls ha-gateway or ai-gateway through secondary gRPC adapters.
5. The bot sends a Discord response. Long-running AI work is tracked so shutdown can wait briefly for in-flight requests.

Commands

Lights

/light list
/light on light:<entity> brightness:80 color_temp:3000
/light off light:<entity> transition:3
/light toggle light:<entity>

• light is required for action commands and uses autocomplete.
• brightness is optional and accepts 1-100.
• color_temp is optional and accepts 2000-6535 kelvin.
• transition is optional and accepts 0-30 seconds.

Switches

/switch list

Switch control commands are not exposed yet. ha-gateway currently only implements switch discovery.

AI

/ai query text:<prompt>
/ai model list
/ai model get
/ai model set name:<model>

AI queries are sent to ai-gateway. The active model is stored in process memory, so it resets when the bot restarts.

Configuration

Environment variables:

Variable	Default	Description
DISCORD_TOKEN	required	Discord bot token
GUILD_ID	empty	Guild-scoped command registration target; empty registers global commands
HA_GATEWAY_ADDR	required	gRPC address for ha-gateway
AI_GATEWAY_ADDR	ai-gateway.home-services.svc.cluster.local:50052	gRPC address for ai-gateway
TLS_DIR	empty	Enables mTLS for gateway clients when set
OTEL_ENDPOINT	empty	OTLP gRPC collector endpoint; empty disables telemetry
LOG_LEVEL	info	debug, info, warn, or error
LOG_FORMAT	json	json or text

Example env file: .env.example

When TLS_DIR is set, the directory must contain tls.crt, tls.key, and ca.crt.

Local Run

cp .env.example .env
go run ./cmd/bot

Run from discord-bot/ so godotenv loads discord-bot/.env.

For local plaintext gateway connections, leave TLS_DIR empty and use:

HA_GATEWAY_ADDR=localhost:50051
AI_GATEWAY_ADDR=localhost:50052

Test And Build

go test ./...
go build ./...

Build the container image from the workspace root:

docker build -f discord-bot/Dockerfile -t discord-bot:dev .

Optionally pass a build version:

docker build -f discord-bot/Dockerfile --build-arg VERSION=$(git rev-parse --short HEAD) -t discord-bot:dev .

Package Map

cmd/bot/                                 # process entrypoint and wiring
internal/adapters/primary/discord/       # slash command registration and handlers
internal/adapters/secondary/gateway/     # ha-gateway gRPC client
internal/adapters/secondary/aigateway/   # ai-gateway gRPC client
internal/app/                            # command orchestration and formatting
internal/config/                         # environment loading
internal/core/ports/driven/              # app-facing gateway interfaces
internal/modelstore/                     # in-memory active AI model store
internal/modelvalidator/                 # model availability checks
internal/logger/                         # slog setup
internal/telemetry/                      # OpenTelemetry setup

Limitations

• Switch commands are discovery-only.
• The active AI model is not persisted.
• The bot relies on Discord auth plus internal gateway/network controls; it does not implement per-user authorization.
• List output is optimized for monospace Discord messages, not rich embeds.