133 lines
3.9 KiB
Markdown
133 lines
3.9 KiB
Markdown
# 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
|
|
|
|
```text
|
|
/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
|
|
|
|
```text
|
|
/switch list
|
|
```
|
|
|
|
Switch control commands are not exposed yet. `ha-gateway` currently only
|
|
implements switch discovery.
|
|
|
|
### AI
|
|
|
|
```text
|
|
/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](https://gitea.nik4nao.com/nik/home-services/src/branch/main/discord-bot/.env.example)
|
|
|
|
When `TLS_DIR` is set, the directory must contain `tls.crt`, `tls.key`, and
|
|
`ca.crt`.
|
|
|
|
## Local Run
|
|
|
|
```bash
|
|
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:
|
|
|
|
```text
|
|
HA_GATEWAY_ADDR=localhost:50051
|
|
AI_GATEWAY_ADDR=localhost:50052
|
|
```
|
|
|
|
## Test And Build
|
|
|
|
```bash
|
|
go test ./...
|
|
go build ./...
|
|
```
|
|
|
|
Build the container image from the workspace root:
|
|
|
|
```bash
|
|
docker build -f discord-bot/Dockerfile -t discord-bot:dev .
|
|
```
|
|
|
|
Optionally pass a build version:
|
|
|
|
```bash
|
|
docker build -f discord-bot/Dockerfile --build-arg VERSION=$(git rev-parse --short HEAD) -t discord-bot:dev .
|
|
```
|
|
|
|
## Package Map
|
|
|
|
```text
|
|
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.
|