mara/hyperhive
mara/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity

swarm-stt: the daemon (queue connection, request/reply, busy limit, hourly purge) and its settings docs

Browse source
This commit is contained in:
damocles 2026-11-11 22:09:09 +01:00 • committed by mara
commit ee10acb154
1 changed files with 237 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

41
docs/4-implementation/swarm/stt.md
View file

@ -39,10 +39,39 @@ way to open them. The service kills a run that outlasts its timeout (decode and
together) and fails the request, so one hung child can't hold the single
engine slot. A scratch directory per run holds the WAV and goes away with the run.
## Settings the daemon will expose
## The daemon
The model (default `small`), the cache TTL (default one day), the size,
length and run-time caps. The daemon change also owns a bound on how many
requests may wait for the engine slot, a sweep of scratch directories a crash
left behind, and whisper's thread count. The design and the choices behind them are in the discussion on
issue 6383.
`swarm-stt` connects to the queue as its own OIDC client, with its secret read
from the store under its own certificate, as the notification router does. It
subscribes to `$SWARM.stt.transcribe.*` in the queue group `swarm-stt` and
answers each request on its reply subject. The body of a request is the raw
audio. The answer is JSON: `{"status":"ok","text":…,"cached":…}` or
`{"status":"failed","message":…}` (`swarm_wire::stt`). An agent may publish
only on its own `$SWARM.stt.transcribe.<agent>`, and the service may publish
nowhere but the inbox of its own client, so replies leave through NATS reply
rights.
The service holds at most `MAX_WAITING` requests at once, whether running or
waiting for the engine's one slot, because each holds its audio in memory. It
answers a request past that with a `failed` response saying it's busy. It
removes expired transcripts every hour.
## Settings
All are environment variables with the prefix `SWARM_STT_`; the nix module will
set them.
| variable | default | meaning |
| ------------------------------------------------------------------- | ------------------------------ | ----------------------------------------------------- |
| `STATE_DIR` | required | holds `cache/` and `scratch/` |
| `FFMPEG`, `WHISPER_CLI`, `MODEL` | required | the two binaries and the ggml model file |
| `CACHE_TTL_SECS` | one day | how long a transcript stays |
| `MAX_BYTES` | 6 MiB | the largest audio file taken; the queue carries 8 MiB |
| `MAX_AUDIO_SECS` | 300 | seconds of audio decoded; ffmpeg drops the rest |
| `RUN_TIMEOUT_SECS` | 300 | the longest one run may take |
| `MAX_WAITING` | 8 | requests held at once |
| `NATS_URL`, `OIDC_TOKEN_ENDPOINT`, `OIDC_CLIENT_ID`, `OIDC_CA_FILE` | required, the CA file optional | the queue connection |
Two things the daemon doesn't do yet: sweep scratch directories a crash left
behind, and set whisper's thread count. The issue 6383 discussion has the
choices behind the defaults.