# 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.