diff --git a/CLAUDE.md b/CLAUDE.md index 5c7ba88..60cb07e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Repo Overview -`home-services` is a Go workspace of three internal services for home control, connected by gRPC and sharing committed protobuf-generated code: +`home-services` is a Go workspace of four internal services for home control, connected by gRPC and sharing committed protobuf-generated code: ```text Discord users @@ -22,8 +22,9 @@ ha-gateway - **ha-gateway** (port `50051`) — gRPC boundary for Home Assistant. Talks to HA's REST API; implements entity state, light control/discovery, switch control/discovery, and climate (HVAC) control/discovery; also relays SwitchBot Cloud remote commands (`RemoteApp`) when `SWITCHBOT_TOKEN`/`SWITCHBOT_SECRET` are set. Event streaming is stubbed. - **ai-gateway** (port `50052`) — gRPC service that turns free-form text into home actions. Calls Ollama for intent extraction, resolves intents against a cached light list from `ha-gateway`, and calls `ha-gateway` to execute approved actions. - **discord-bot** — registers `/light`, `/switch`, `/ac`, `/ai` slash commands and calls `ha-gateway`/`ai-gateway` via gRPC clients. +- **tts-gateway** (port `50053`) — gRPC text-to-speech service (VITS voice model, 92 Umamusume voices), paired with a Python/libtorch inference sidecar (`tts-gateway/sidecar/`, deployed as a second container in the same pod) that needs an Nvidia GPU — see `TTS_GATEWAY_PLAN.md` for why. Not yet wired into the diagram above; nothing calls it yet (a discord-bot `/speak` command is the planned follow-up). See `tts-gateway/README.md` for its API/config/local-run details. -Each service is a separate Go module (own `go.mod`) joined by `go.work` at the root, plus a `gen` module for shared generated code. Module paths are `gitea.nik4nao.com/nik/home-services/{ha-gateway,ai-gateway,discord-bot,gen}`. +Each service is a separate Go module (own `go.mod`) joined by `go.work` at the root, plus a `gen` module for shared generated code. Module paths are `gitea.nik4nao.com/nik/home-services/{ha-gateway,ai-gateway,discord-bot,tts-gateway,gen}`. ## Architecture (hexagonal, per service) @@ -43,14 +44,14 @@ internal/telemetry/ # OpenTelemetry setup `internal/core` has no dependency on adapters — ports are interfaces that adapters implement (driven) or call into (driving). When adding a capability, the usual path is: define/extend a port in `core/ports`, implement orchestration in `app`, then wire an adapter in `adapters/primary` or `adapters/secondary`. -Protobuf contracts live in `proto/` (buf module, `ai/v1` and `ha/v1` packages). Generated Go code is committed under `gen/` and consumed by all three services through the Go workspace — do not hand-edit files in `gen/`. +Protobuf contracts live in `proto/` (buf module, `ai/v1`, `ha/v1`, and `tts/v1` packages). Generated Go code is committed under `gen/` and consumed by all four services through the Go workspace — do not hand-edit files in `gen/`. ## `tmp/` is reference-only, never a dependency `tmp/` is gitignored — nothing under it is pushed to git, and it should be treated as temporary scratch space for reference material (e.g. `tmp/reference/switchbot-control-reference/`, a standalone CLI copied in for local discovery/testing against an external API). Rules: - It's fine to read code under `tmp/` for patterns, to run its scripts/tools locally (a discovery script, a CLI, etc.), or to use it as a manual testing aid. -- Never make any of the three services (`ha-gateway`, `ai-gateway`, `discord-bot`) import, `go.work use`, or otherwise depend on anything under `tmp/` at build or runtime. Since `tmp/` isn't committed, that dependency would silently break for every other clone of the repo (including CI). +- Never make any of the four services (`ha-gateway`, `ai-gateway`, `discord-bot`, `tts-gateway`) import, `go.work use`, or otherwise depend on anything under `tmp/` at build or runtime. Since `tmp/` isn't committed, that dependency would silently break for every other clone of the repo (including CI). `tts-gateway/sidecar/` is a real example of doing this correctly — its model code was copied out of `tmp/reference/uma-tts-api/` into a committed location rather than referenced in place. - If a reference tool under `tmp/` lives in its own Go module nested inside this repo's `go.work` workspace, invoke it with `GOWORK=off` rather than adding it to the root `go.work` — e.g. `GOWORK=off ./scripts/some-tool ...` from that tool's own directory. - If something under `tmp/` turns out to be genuinely needed at runtime, port the actual logic into the relevant service's `internal/` tree (following the hexagonal layout above) instead of reaching into `tmp/` from committed code. @@ -65,8 +66,8 @@ buf generate Run tests / vet (from repo root, or `cd` into a service and drop the prefix): ```bash -go test ./ha-gateway/... ./ai-gateway/... ./discord-bot/... -go vet ./ha-gateway/... ./ai-gateway/... ./discord-bot/... +go test ./ha-gateway/... ./ai-gateway/... ./discord-bot/... ./tts-gateway/... +go vet ./ha-gateway/... ./ai-gateway/... ./discord-bot/... ./tts-gateway/... ``` Run a single test: @@ -78,7 +79,7 @@ cd ha-gateway && go test ./internal/app/... -run TestEntityAppGetState Build binaries: ```bash -go build ./ha-gateway/... ./ai-gateway/... ./discord-bot/... +go build ./ha-gateway/... ./ai-gateway/... ./discord-bot/... ./tts-gateway/... ``` Run a service locally (each loads `.env` from its own working directory via `godotenv`, so `cd` into the service dir first): @@ -89,6 +90,10 @@ cd ai-gateway && cp .env.example .env && go run ./cmd/gateway cd discord-bot && cp .env.example .env && go run ./cmd/bot ``` +`tts-gateway` additionally needs the `open_jtalk` CLI/dictionary/voice, `ffmpeg`, and a running +inference sidecar to actually synthesize anything — see `tts-gateway/README.md` for the full +local/nik-gpu run instructions rather than a short snippet here. + For local plaintext dev, point gateways at each other with `TLS_DIR` empty, e.g. `HA_GATEWAY_ADDR=localhost:50051`, `AI_GATEWAY_ADDR=localhost:50052`. Build container images (from repo root, since Dockerfiles reference the whole workspace): @@ -97,6 +102,8 @@ Build container images (from repo root, since Dockerfiles reference the whole wo docker build -f ha-gateway/Dockerfile -t ha-gateway:dev . docker build -f ai-gateway/Dockerfile -t ai-gateway:dev . docker build -f discord-bot/Dockerfile -t discord-bot:dev . +docker build -f tts-gateway/Dockerfile -t tts-gateway:dev . +docker build -f tts-gateway/sidecar/Dockerfile -t tts-sidecar:dev tts-gateway/sidecar ``` gRPC smoke checks (with the relevant service running): @@ -108,6 +115,9 @@ grpcurl -plaintext -d '{"text":"turn on the desk lamp","source":"local"}' localh grpcurl -plaintext -d '{}' localhost:50052 ai.v1.AIService/ListModels ``` +`tts-gateway`'s smoke check needs the sidecar (and, for real inference, a GPU) up first — see +`tts-gateway/README.md` rather than duplicating the fuller sequence here. + Note: `ha-gateway` always registers gRPC reflection; `ai-gateway` only registers reflection when `LOG_LEVEL=debug`. ## Testing Conventions @@ -124,10 +134,12 @@ Tests use the standard library `testing` package only (no testify). Mocks are ha ## nik-gpu deployment target -`tts-gateway` (planned in `TTS_GATEWAY_PLAN.md`) is designed to run on `nik-gpu`, a remote Nvidia -GPU host reachable via `ssh nik-gpu`, managed through the Claude Code skills `nik-gpu-status` -(read-only check), `nik-gpu-sync` (rsync this repo to `~/repo/home-service/` there), and -`nik-gpu-docker-build` (build/smoke-test via a `nik-gpu` Docker context). +`tts-gateway`'s inference sidecar (see `TTS_GATEWAY_PLAN.md` for the full history) runs on +`nik-gpu`, a remote Nvidia GPU host reachable via `ssh nik-gpu` — both for local dev/smoke-testing +(via the Claude Code skills `nik-gpu-status` (read-only check), `nik-gpu-sync` (rsync this repo to +`~/repo/home-service/` there), `nik-gpu-docker-build` (build/smoke-test via a `nik-gpu` Docker +context), and `tts-gateway/README.md`'s run instructions) and as the actual GPU node backing the +production Kubernetes deployment — see "Infrastructure / Deployment" below. **Never automatically run installation or other host-system-altering commands on nik-gpu** — `apt`/`apt-get`, `pip install` outside a container, Docker daemon config changes, driver/toolkit @@ -137,6 +149,38 @@ bare nik-gpu host specifically; installing packages *inside* a Dockerfile build `apt-get install open-jtalk` as a build step) is a normal container build action, not a host mutation, and is fine to run. +## Infrastructure / Deployment + +This repo builds and pushes Docker images (see CI below) but does not deploy them. Actual +deployment — Kubernetes manifests, Secrets, GPU scheduling — lives in a **separate** repo: +`~/repo/homelab`, specifically `manifests/home-services/*.yaml`. That covers Deployments/Services +for all four services here (namespace `home-services`), plus cluster-level pieces like +`nvidia-device-plugin.yaml` and sealed secrets (`*-sealed.yaml` manifests generated from +`*-secret.sh` scripts, one pair per service that needs one — `tts-gateway` doesn't have one yet, +since unlike `ha-gateway`/`discord-bot` it currently needs no external tokens/credentials). + +When a question is about how something actually behaves *in production* — not just what the code +does — check that repo before guessing or assuming something isn't deployed; this repo alone +doesn't show the full picture. Specifics of what's actually in `tts-gateway.yaml` there (current +as of 2026-07-25 — it's maintained independently of this repo, so verify against the live file +rather than trusting this description to stay accurate): + +- `tts-gateway` and `tts-sidecar` run as **two containers in one Pod**, not separate Deployments — + the Go gateway reaches the sidecar over `localhost:50054`, mirroring the `--network host` + pattern documented in `tts-gateway/README.md` for local Docker testing. +- GPU scheduling: `runtimeClassName: nvidia`, `nodeSelector: nik4nao.com/gpu: "true"`, and + `nvidia.com/gpu: 1` request/limit on the sidecar container. `strategy: Recreate` instead of the + default `RollingUpdate` — nik-gpu only has one allocatable GPU, so a rolling update would + deadlock waiting for a GPU still held by the pod it's replacing. +- Model artifact distribution (checkpoint + hparams) is a `hostPath` volume at + `/data/tts-gateway` on the nik-gpu node, not baked into the image or automated — someone has to + manually place `G_790000.pth`/`uma.json` there. This is a known-open gap (see `handoff.md`), + not a deliberate final design. +- mTLS (`TLS_DIR`) is currently commented out on `tts-gateway`, for plaintext `grpcurl` testing + from outside the cluster during initial rollout — a live TODO, not a permanent decision, unlike + every other service here which assumes mTLS-or-trusted-network as its only access boundary (see + "Configuration Notes" above). + ## CI `.gitea/workflows/ci.yaml` always runs `go vet`/`go test` for all five modules (`gen`, `ai-gateway`, `ha-gateway`, `discord-bot`, `tts-gateway`) on every push/PR. On pushes to `main`, a `changes` job (`dorny/paths-filter`) determines which of the five images actually need rebuilding based on which paths changed, so an edit scoped to one service doesn't rebuild (and re-push) all of them — `gen/`, `go.work`, and `go.work.sum` count as shared and mark every Go-based image as changed, since a dependency bump there can affect all of them. Each `build-*` job is gated on that output and, when it runs, uses `docker/build-push-action`'s registry-based cache (`cache-from`/`cache-to: type=registry,ref=.../:buildcache`) so unchanged Docker layers (e.g. `go mod download`, `apt-get`/`pip install`) don't get redone on every run — the *first* run after adding this has nothing to pull from and builds fully fresh, subsequent ones should be much faster. `tts-sidecar` (the Python/CUDA inference sidecar under `tts-gateway/sidecar/`) is a large ~13GB image; it builds fine on a generic runner since only *running* it needs a GPU, not building it.