Configuration

Reference first, reasoning second. Where a Why drawer sits under a setting, that is the argument for the way it currently behaves — collapsed rather than cut, because it is worth reading once and in the way every time afterwards. Nothing you would search this page for is inside one: names, defaults, and boundary values stay in the tables.

The file

config.yaml is mounted at /config/config.yaml from a ConfigMap. Point CONFIG_FILE elsewhere to override the location. The file is read once at startup, so editing it means restarting the pod. The IDs in the repo copy are placeholders.

settings:
  quotes:
    backoff: 5m
  fines:
    volume_floor: 0.25

servers:
  123456789012345678:
    alias: first-server
    users:
      234567890123456789: Speaker One
    tools:
      scoreboard:
        enabled: true
      summary:
        enabled: true
        config:
          monitored_channels:
            general-voice:
              channel: session-summaries
      tts:
        enabled: true
      verbal-morality:
        enabled: true
        config:
          words: [fiddlesticks, poppycock]

  876543210987654321:
    alias: second-server
    users:
      234567890123456789: Someone Else

summary is what puts a room on the record. A server that does not enable it, or a voice channel absent from its monitored_channels, is still joined and still heard — and nothing said there reaches disk. That is one switch rather than four, and it is the line to check first when a bot that is plainly working leaves an empty transcript directory behind.

Hosts, ports, directories, and the token are environment variables; everything that is a number or a wording is settings:. settings: is optional in its entirety, and so is every line in it — a file that mentions none of them is a working file. It is not, however, free-form: a name nothing reads is reported at startup, and a value that will not parse falls back to its default and is reported too.

Parsing reports rather than raises

A malformed server block — no alias, or not a mapping at all — is dropped and logged; so is a name filed under something that is not a user ID, and a tool whose settings will not parse. The bot joins one fewer server instead of crash-looping over a typo.

On startup it also reconciles the file against the servers it is actually in. Four things can be wrong and none of them raise: an entry would not parse, nothing is configured, a server is configured but the bot was never invited, or the bot is in a server nobody configured. Each is logged — see reading the startup log.

Servers

Everything about a server lives under its ID, and the ID appears there and nowhere else.

servers is a hard gate on joining. A server that is not listed is never joined, by autojoin or by an explicit !mq join, and an empty mapping or a missing file means the bot joins nothing at all.

users

users:
  234567890123456789: Speaker One
  "345678901234567890": Speaker Two

users replaces the display name Discord reports for a speaker. IDs may be quoted or bare; both are read as integers. The roster is per server, and it is also what can be warmed and who is eligible for the scoreboard — a phrase naming somebody on it is rendered before anybody speaks, and somebody not on it waits for the synthesizer the first time they are named.

tools

tools elects the server into the tools listed under it. Each is opted into on its own, including the ones others depend on — verbal-morality hands its fines to scoreboard and its words to tts, and enabling it alone fines people silently and keeps no record of it. Each absence is reported at startup.

A tool block holds enabled and config, and nothing else. Every setting a tool takes goes under config:; written a level up, beside enabled, it is read by nothing and named at startup:

      quotes:
        enabled: true
        penalize_self_answers: false   # ← wrong: reported at startup, read by nothing
        config:
          penalize_self_answers: false # ← right

Two tools that require each other are a circle, reported at startup and left unbuilt — see the tool contract.

Everything in this block is what the server starts as. !mq changes what it is doing now, without a restart and without touching the file; see switching things on and off.

Switching things on and off

!mq is everything typed at the bot: where it sits, and what one server is doing right now. !miss-quote is the same command written out. It refuses any server not listed under servers.

Reading or changing what a server is doing requires Administrator. Coming and going does not — a room with AUTOJOIN off has no other way to be heard at all.

Nothing here is written down. A restart goes back to config.yaml, which is why !mq lists what the file says beside anything that no longer matches it:

quotes             on
scoreboard         on
summary            off  file says on
tts                on
verbal-morality    on
transcribing       on

A tool switched off keeps everything it knew. It hears nothing, no other tool can reach it, and whatever it was running of its own stops — but the instance survives, so switching it back on restores the backoff windows, the round in progress, and the running tally intact.

Setting one of a tool’s own settings rebuilds it, and a rebuilt tool has forgotten all of that. A tool reads its config once and turns it into compiled patterns and expanded word stems, so a new value means a new instance. A value the tool refuses leaves the running one exactly as it was, and says what it objected to.

A tool the file never enabled can still be switched on, provided its config: block is there to build from — enabled: false with settings underneath is read either way. One that needs config it has not got reports what it wanted rather than starting broken.

Tools

Five tools ship. A name nothing answers to is reported at startup and skipped, the registry being a closed list rather than whatever happens to be importable.

quotes

Answers the channel with the film line it just walked into. It listens for a trigger phrase and, on hearing one, says the associated quote out loud where it was said — and then asks where the line came from.

quotes:
  enabled: true
  config:
    quiet: 1s
    chance: 1
    answer: 10s
    tie: 1s
    remarks:
      - having watched it more recently than is respectable.

The quote file

The lines come from a YAML file at QUOTES_FILE — a film, and under it the phrases that set its lines off. The image ships the list in resources/quotes.yaml; mount your own over that path to replace it.

Firefly:
  cool: Shiny.
  behave: I aim to misbehave.

Project Hail Mary:
  question: "{user} question is dumb."

The Princess Bride:
  impossible: Inconceivable!

A trigger appears once in the whole file, including across titles. The first is kept and the rest reported, so the line to go and delete is the later one.

Two triggers may share an answer — awesome and cool both earning Shiny.. There is no alternation syntax inside a trigger, so a key meaning to catch two phrases has to be two keys.

A phrase worth answering several ways lists its lines, and one of them is drawn each time it fires:

Firefly:
  cool:
    - Shiny.
    - Gorram it.

The draw happens when the trigger fires rather than at startup, so a restart does not decide which line a channel hears for the next week. The backoff is still keyed on the trigger, so a trigger with four answers fires once per window, not four times.

Two things are worth knowing about the format itself, because both look entirely correct in the file:

• A line starting with {user} has to be quoted. Unquoted, a { opens a mapping and the file will not parse.
• A trigger like no or a title like 1917 has to be quoted too. Unquoted, YAML reads them as a boolean and an integer, and neither is text the matcher can ever compare against.

The file is read at startup and reports rather than raises: a bad entry is logged with its line number and dropped. What does stop the tool starting is a file that is missing, unreadable, not valid YAML, not a mapping of titles, or holding no usable entry at all.

Because a dropped entry is a line in a log nobody reads, the file is also checked before it can be merged. scripts/validate_quotes.py applies the loader’s rules where a broken entry fails a pull request instead, plus the ones the loader has no opinion about:

It needs PyYAML and nothing else, so it runs in seconds on every pull request rather than costing an image build.

What a server adds for itself

A server with an in-joke of its own writes it under additional_quotes, in its config block and in the file’s own shape:

quotes:
  enabled: true
  config:
    answer: 10s
    additional_quotes:
      Firefly:
        cool: Shiny.
        behave: I aim to misbehave.
      "1917":
        over the top: "Over the top, {user}!"

Everything the file can say, this can say, and the same rules apply — including the two quoting traps: a title like 1917 and a line starting with {user} both need their quotes. A server keeping its list in a file of its own writes that file’s name here instead; see keeping that list somewhere else.

• A failed entry never stops the tool. The block is optional, and a server that gets it wrong still has the whole shipped list.
• A trigger the shipped list already answers is overridden by this server’s line, for this server alone. The next server on the same deployment hears the shipped line.
• Titles merge. Firefly written in both places is one film with everything either said under it, and a round asks about the same title either way.
• CI checks these too. scripts/validate_quotes.py --config config.yaml walks every server’s block. A trigger shared with the shipped list is the override, not a collision.

Keeping that list somewhere else

A list long enough to be worth its own file does not have to live in config.yaml. Write additional_quotes as one string instead of the quotes themselves — a path on disk, mounted wherever the rest of the deployment’s configuration is:

quotes:
  enabled: true
  config:
    additional_quotes: /config/quotes/beer-wars.yaml

or somewhere to download it from, which is read once on the way up:

quotes:
  enabled: true
  config:
    additional_quotes: https://quotes.example.com/beer-wars.yaml

A string beginning http:// or https:// is downloaded; anything else is a path, where a leading ~ is the home directory. The scheme is the whole rule — there is no second key saying which.

A file it cannot get is a log line and nothing worse — missing, unreadable, bad YAML, or a server that will not answer. The server keeps the whole shipped list. Only the deployment’s own file can stop the tool starting.

A dropped entry names the line it was written on, which an inline block cannot do: config.yaml has been parsed by the time the tool sees it, and a file it points at is still a file.

CI does not follow the name. validate_quotes.py --config leaves a path or URL alone, making no network calls. Check the file behind it by passing it in like any other quote file:

python scripts/validate_quotes.py quotes/beer-wars.yaml --config config.yaml

Matching and backoff

Matching is whole words, case-insensitive, so real does not fire inside really. A phrase trigger matches on a single space between its words, which is what an ASR transcript holds.

One line per utterance, however many triggers were in the sentence. The one that answers is the earliest in the sentence rather than the first in the file; where two start at the same word, the longer wins.

A trigger that has just fired goes quiet for backoff — the server’s own, or settings.quotes.backoff, five minutes by default. The window is keyed on the trigger, not the speaker and not the line, is per server, and is held in memory only, so a restart forgives every backoff.

The whole list is rendered at startup, the triggers and answers both being a closed set. A line naming whoever set it off is rendered once per name on the roster instead.

Letting the speaker finish

A line waits for whoever set it off to stop talking, quiet of it — one second by default. The window starts again every time that speaker says something else, so what is waited out is them finishing rather than a fixed pause. Only their own utterances count.

A speaker already holding a line sets nothing else off while they are still going; they can still answer a round somebody else opened. The round opens when the line has finished playing, so the wait moves the question along with it. quiet: 0 says the line where it was heard, interruption and all.

Answering only some of it

chance is the odds a trigger is answered at all, between 0 and 1, and everything by default. At 0.5 a phrase comes back about every other time it is said.

The roll is once per utterance, not once per trigger, so a sentence carrying three is answered as often as one carrying one. A roll that goes the other way spends nothing — the trigger is not put on backoff. Values outside the two ends are held at them, and 0 answers nothing at all.

Naming it

A line that has been said is also a question. For answer afterwards the channel can say where it came from — what is Firefly — and whoever does is paid a credit through scoreboard, and told so out loud.

The window opens when the line has finished playing, not when the trigger was heard: transcription and synthesis take as long as they take, and a window started at the trigger could be over before the channel had heard the question.

The first correct answer takes the round, and anyone inside tie of it is paid as well. Nobody is paid twice for the same title however many times they say it.

Answers are matched forgivingly, because an ASR transcript is not punctuated the way a poster is:

The answer may sit anywhere in the sentence. A row with an empty movie asks nothing, there being no question in it. A title carrying a numeral is matched as a numeral — Apollo 13 answers to what is apollo 13 and not to what is apollo thirteen, which is what an ASR is likelier to return; write the title the way it will be transcribed if that matters.

Two rounds can be open at once, since an answer names its own title. An utterance that answers an open round is an answer and nothing else, whatever trigger it also contains — otherwise a channel naming a title could set off the line asking about the next one, a loop the tool would be driving rather than following.

A server with no scoreboard asks the question and pays nothing, which is said once at startup.

The announcement

The award is said out loud, with no chime in front of it — a fine opens with one because it interrupts something else, while an award answers a question the channel is already sitting in.

Correct! Erik, you are awarded 1 credit for quoting along at home.

The ending is drawn fresh each time, from the list the tool ships with plus whatever remarks adds to it — one fixed sentence is a joke told once and then endured. The shipped endings are:

• knowing exactly where that came from, which explains a great deal.
• quoting along at home.
• a display of recall that has never once been useful.
• having excellent taste and nothing better to do.
• being the sort of person who knows that.
• spending your formative years exactly as you did.

remarks adds to those rather than replacing them. None of the shipped endings says “film”, and the movie key is named more narrowly than it behaves — a trigger answers for a series, a game, or a book as often as a picture, and an announcement that guesses wrong guesses wrong out loud. Write your own the same way.

Announcements the model writes

Six endings are enough to be a joke and not enough to be a joke twice. With generated_point_responses: true the bot also asks the model for whole announcements of its own — complete sentences carrying {user} and {credits}, drawn on beside the shipped endings rather than instead of them.

quotes:
  enabled: true
  config:
    generated_point_responses: true
    generated_catalogue_size: 50
    generated_response_count: 5
    generated_interval: 1h

This needs an endpoint: LLM_API_BASE and LLM_MODEL, the same two settings.llm points summary at. With nothing answering there, rounds are announced with the wordings the tool ships with and the log says so once.

It works in two stages, and the split is the point:

• The catalogue is written once, at startup, in batches, and held in memory for the life of the process. The model is never asked again.
• The live set is generated_response_count drawn from that catalogue at random, rendered, and made current for generated_interval before a fresh set is drawn.

A draw only ever happens while the bot is in a voice channel, and the phrases it picked are synthesized before they go live — so nothing is ever said that was not already rendered, and a server nobody is sitting in costs a sleeping task and nothing else. Joining a channel draws a first set immediately rather than waiting out the interval.

Anything the model writes that will not interpolate is dropped rather than said: a sentence naming no winner, one asking for a {remark}, or one with a stray brace in it. A short catalogue is a short catalogue; the shipped endings are still there.

Somebody paid on a tie gets the second wording — Eli, you are also awarded 1 credit, for getting there at the same time. — because the whole sentence again reads as though the bot had lost track of what it just said.

Nothing this tool says is dropped for landing while something else is playing, unlike verbal-morality: everything quotes says answers something it just said itself. Announcements wait their turn on the speaker’s per-server lock and come out in the order they were earned.

Naming your own line

Whoever set a line off cannot name it. An attempt is refused out loud and costs them self_answer_penalty credits:

Nuh uh uh. Erik, you set it off, so you do not get to name it. You are fined 5 credits for being a dick.

The penalty is taken once per round however many times they say it, and an attempt neither wins the round nor spoils it — whoever names it next is the first answer and is paid in full. The bar is per round, not per person. penalize_self_answers: false drops the rule entirely.

summary

Writes down what happened in a voice channel once the bot leaves it, and reads it back out loud when somebody asks. It is the only tool that uses the finished-transcript moment.

summary:
  enabled: true
  config:
    monitored_channels:
      general-voice:
        channel: session-summaries
        schedule:
          - Wed 17:00-00:00

That is a working block. Everything else has a default.

Which channels

monitored_channels is the switch as well as the settings. A channel not in it is not transcribed, not summarized, not posted, and does not answer the question either — one rule rather than four. The consequence is worth stating plainly: turning this tool off stops the server writing anything down. See the capture schedule.

Keys are matched through the same slug that names the transcript directory, so General Voice and general-voice are the same channel, and the key you write is exactly the directory the summaries land in.

Per-channel settings

One evening, several sessions

A transcript is one connection to a voice channel, and a room produces several in a night — everybody steps out, somebody drags the bot next door, a pod restarts.

Where the room is on a schedule, what gets summarized is the window. Every session that opened inside one occurrence of a window is summarized together, under the name of the session that opened the sitting. Each subsequent seal rewrites that one file, and edits that one message in channel, so the evening leaves a single account that gets fuller rather than four overlapping ones.

• Which occurrence a session belongs to is decided by when it opened. A window says when a sitting may start, not how long it may run, so a session opening at 23:40 inside Wed 17:00-00:00 and sealing at 01:20 is part of Wednesday’s evening.
• Overlapping windows count as one stretch, from earliest start to latest end. Back-to-back windows (Wed 17:00-00:00 and Thu 00:00-02:00) are separate sittings, the interval being half-open.
• minimum_utterances is measured against the whole sitting, so two visits of three lines are a conversation where either alone would not be. A session that wrote nothing down triggers no rewrite.
• Outside a window, nothing changes. A session opened by !mq transcribing on, or in a deployment with no schedule at all, is summarized on its own under its own name.

The first message of an account is pinned, and that is how an evening is found. An account that still fits its messages is rewritten in place; one that has outgrown them is posted again whole and the old run deleted, which takes its own pin off the list.

Showing it as it is said

post_transcripts puts the last transcript_lines of what the room has said into one message in the same channel the summary goes to, and rewrites it as the room talks. It is off unless a channel asks for it: the transcript on disk is a file in a volume with a retention window, while the same words in a text channel are permanent, searchable, and readable by everyone in the server rather than everyone who was in the room.

It needs Pin Messages, which Manage Messages does not carry. Discord split the two apart, so a bot trusted to delete anybody’s message can still be refused a pin. Without it the feed works unpinned and says so once per session in the log. Posting needs Send Messages; editing and deleting its own messages is ungoverned.

transcript_lines is a maximum rather than a promise. A ring holds lines and a message holds characters, so the feed shows as many of the newest lines as fit and drops the oldest off the top — whole lines, never a cut partway through the block.

A long line costs the lines above it rather than its own tail. There is no cap on one utterance unless a channel sets transcript_line_limit, which puts an … on anything longer.

It writes on change, not on a timer, waiting out transcript_refresh from the end of each write. A quiet room costs nothing, a burst of four people landing together is one edit, and a slow Discord slows the feed instead of building a backlog. Below 0.25 is held there.

It comes down when the room does, deleted as the session seals rather than after the summary is written. The next session posts a new one; what the evening leaves behind is the summary.

Writing it down

When a session seals — after the resume window, or immediately on shutdown — the JSONL is reduced to the two fields a summarizer wants:

Erik: that should work
Eli: it did not

Consecutive lines from one speaker are joined. That goes to the endpoint with the channel’s prompt, and what comes back is written to SUMMARY_DIR and posted to the channel named in channel: — by name, resolved when it is posted, so a renamed channel silently stops receiving posts and an unresolvable one is reported at startup. Leaving channel: out writes to disk and posts nothing.

A session under minimum_utterances is not summarized. A failure anywhere costs the summary and nothing else — nothing partial is written or posted, and the transcript is untouched, so a session missed because the endpoint was down can be summarized by hand later.

A whole session is sent in one request, and it is not truncated. A long evening is tens of thousands of tokens, and an endpoint whose context will not take it refuses the request — logged, no file, no post, transcript intact. Point LLM_MODEL at something with the context to hold a session.

Keep settings.llm.timeout well under terminationGracePeriodSeconds. A session sealed as the pod goes down is summarized inside the shutdown, so a whole LLM round trip runs inside the grace period and can be killed by it.

Reading it back

“Miss Quote, what happened last session” and the bot tells you, out loud, having run the stored summary through a second prompt that turns a thing you read into a thing you say.

It answers for that channel, with the whole of the evening asked about — a run of sessions, not one file. A session still in progress has no summary yet, so this is the previous conversation even asked in the middle of one.

Asking takes both a name and a trigger, the name first; punctuation is ignored on both sides. Several spellings of the name ship by default, an ASR guessing phonetically at a name it has never been told.

It does not have to be one breath. A name said with no question after it is held for address_window, fifteen seconds by default, so that speaker’s next utterance can finish the question. It is per speaker, and 0 wants the whole question at once. A question that named no evening then waits clause_window, a second and a half, to see whether one is still coming — covered by the preamble, so it costs nothing to listen to.

What none of this recovers is the two halves arriving the other way round: transcription runs several at a time, and an utterance is stamped when it is written rather than when it was said, so there is nothing to sort by.

A trigger is the start of a question rather than the whole of one, and what follows it says which evening:

Ordinals are spelled out because that is what an ASR returns; digits work too, but a bare number is not a date — “recap the three things” is about something else. A named day resolves to one of the last two months, earlier this month if it has already been and the month before if it has not, with today counting as “has not”. A day the resolved month does not have gets the missing line rather than sliding to a date nobody named. Counting back weeks gets a few days of latitude, ties going to the later evening; naming a day gets none.

A trigger has to be followed by one of those clauses or by nothing at all, which is what keeps “Miss Quote, what happened to my beer” from being a question about last Thursday.

The bot plays the pre-rendered preamble and starts the inference before it starts saying it, so the announcement covers the wait. The lookup happens first, so it never announces that it is going to look and then finds nothing: with nothing to find it says the empty line, or missing if the trouble is the night that was named.

A second ask while a retelling is still going is dropped rather than queued. backoff is per evening rather than per channel, since somebody asking about a different night is asking a different question.

The retelling itself is never cached — it is composed for one moment and nobody will ever ask for those exact words again. The preamble, the empty line, and a closing are kept.

Hold music

A completion routinely runs longer than the preamble, and what is left over is dead air. hold_music fills that.

It is off unless a channel names a clip, and nothing is shipped. Drop a 16-bit WAV in SPEECH_DIR/chimes and name it here without its extension. It loops, so author a short passage that meets itself — ten to thirty seconds, not three minutes, since a clip is read into memory whole and held for the life of the process.

• It fades up over settings.tts.hold_fade_in (500 ms) as soon as the preamble ends. Quickly, because the gap it is covering has already started.
• It loops for as long as the wait lasts — the model thinking, and then the synthesizer starting on the answer. Both are covered: a completion that returns instantly still leaves the lead head start to be waited out.
• It fades down over settings.tts.hold_fade_out (2 s), starting only once the first speech is in hand, so the music reaches silence exactly where the first word begins rather than being cut off at it.

The music and the retelling are one clip, armed once — two calls would put a gap exactly where this is trying not to have one. hold_volume applies to the music alone; the retelling arrives at the loudness it would have had anyway. A clip that is missing or will not parse costs the music and not the answer, and the name is checked at startup but kept regardless, so a volume mounted later starts working without a restart.

The story ends itself. A retelling ends wherever the model chose to, so a channel listening has no way to tell “finished” from “stopped”. bard is told to close on a line that means the tale is over. closing is the other way: a fixed sentence after the story, unset by default, since a fixed line following one that has just said goodbye is one goodbye too many.

Prompts

Prompts are named and selected by name. Three ship, as prose in src/miss_quote/resources/prompts.yaml:

prompts: adds your own, and one written under a shipped name replaces it. It sits at the tool level rather than inside a channel, a prompt being a library entry rather than a per-room setting.

A prompt of your own can pull in the text the shipped ones share by naming it in braces:

Any other braces are left exactly as written, so an example of the JSON you want back survives. A shipped prompt naming a fragment that does not exist stops the bot at startup; one of your own is left alone, braces in it usually being deliberate.

A prompt named by a name nothing answers to stops the tool from starting. A tool running on instructions nobody asked for produces summaries that look fine and are not what the file requested, which is worse than a tool that refuses.

scoreboard

Keeps a running balance per person, writes it down, and puts the standings under the name of whatever voice channel the bot is in. It hears nothing and says nothing out loud; what it does is count for the tools that ask it to.

scoreboard:
  enabled: true

There is nothing to configure per server. What the tally is counted in and how often it is written and published are settings.credits; where it lives is CREDITS_FILE.

It is enabled separately from whatever is counting. A server enabling verbal-morality and not this announces fines and keeps nothing, which the log says once at startup.

It needs Set Voice Channel Status — not Manage Channels. What it sets is the channel’s status, a voice channel having no topic. Without the permission the tool logs once per change and keeps counting.

The standings read Eli: -9 Erik: -2 Luke: -1 Ryan: 0, holding the four furthest into the red, worst first, ties breaking on the name. They go up as soon as the bot takes up a channel and stay current while it sits there; a channel it leaves keeps the last board it was shown.

• A fine is a debit. Everybody starts at nothing and goes down. Nothing assumes that direction — quotes calls credit, so a balance can climb back toward nothing and past it.
• Only users are eligible. Everyone on the roster starts on the board at nothing spent. Somebody not on it is still heard, announced, and counted, just not published. A server with no roster publishes nothing rather than an empty line.
• Counts are per server, keyed on the user ID, so a rename does not hand somebody else’s debt to whoever inherited their nickname.
• A restart is not an amnesty. The tally is loaded from CREDITS_FILE at startup, written back on save, and written again on shutdown. A file that will not parse is reported and ignored.

tts

Says things out loud, and is the only thing that plays anything. It hears nothing and decides nothing; what it does is own the rendered-speech cache, the chime library, the volume, and the voice connection, so that everything a channel hears arrives by one route.

tts:
  enabled: true

There is nothing to configure per server. Which synthesizer, which voice, and how a clip is handled are settings.tts and TTS_HOST / TTS_PORT / TTS_VOICE. All this setting says is whether this server is allowed to speak through it.

It is enabled separately from whatever is talking. A server enabling verbal-morality and not this counts fines and says nothing; one enabling quotes and not this runs its rounds, pays them, and answers nobody. Both are said once at startup.

Other tools speak through it. play is the whole interface, and play_held is play for a sentence that does not exist yet, so hold music and the answer come out as one clip. chime names a WAV in SPEECH_DIR/chimes without its extension; a missing chime costs the chime and not the announcement.

Rendering in advance is its run. A tool that knows at startup what it will have to say hands over the list, and this renders it in the background, one phrase at a time across the whole process. A phrase that will not synthesize is a line in the log and then the next phrase, never the end of the run.

verbal-morality

The Verbal Morality Bot, after Demolition Man. It listens for words the server has decided against and, on hearing one, announces the fine out loud in the channel it was said in. The credits are imaginary but they are counted, by somebody else: the fine is handed to the server’s scoreboard. With no scoreboard enabled the fine is announced and not counted, which the log says once at startup.

verbal-morality:
  enabled: true
  config:
    words: [fiddlestick, poppycock]
    announcement: "{user}, you are fined {credits} for {violations} of the verbal morality statute."
    repeat_announcement: "{user}, you are also fined {credits} for {violations} of the verbal morality statute."
    recall_announcement: "{user}, you said {word}."
    chime: chime

All three templates default to the lines above, which the tool carries, so a server that wants the defaults can leave them out. A template with a placeholder nothing fills is rejected at startup rather than at the moment someone swears, and the error names which setting it was and which placeholders that one actually has — recall_announcement has {user} and {word}, and reaching for {credits} in it is refused.

Words are stems

Each word in words is a stem, expanded at startup into the endings it is said with, so fiddlestick also catches fiddlesticks, fiddlesticked, fiddlesticking, fiddlestickin, fiddlesticker, and half a dozen more. Matching is whole words, case-insensitive — a substring match fines Scunthorpe.

Two things to check before a stem goes in the list. Its endings can reach a word that is innocent on its own. And a compound may conjugate wrong: the rules use syllable count where English uses stress, so dipshit correctly takes dipshitting only because it is named in COMPOUND_ENDINGS in utils/stems.py, which is the one line to add to.

What a fine costs, and how loudly

The settings named in this section — repeat, recall, backoff, backoff_percent, volume_floor, dampen_after, and dampen — are written either here, in this server’s config, or in settings.fines for every server that names none of its own. This server’s wins.

The fine scales with the utterance: one credit per forbidden word in it. {credits} is filled in already pluralized and as a numeral; what a credit is called is settings.credits.currency, pluralized by the same spelling rules the word list uses, so penny announces as 2 pennies. {violations} reads a violation for one and multiple violations for more.

What does not scale is the number of announcements. Three violations in one utterance earn one, and a violation earned while an announcement is playing is counted and not announced at all. The tally is charged either way.

Being fined twice in a row is worded differently. A speaker fined again inside repeat gets repeat_announcement — “you are also fined”. It is per speaker.

A repeat offender is announced more quietly. Every violation inside a sliding backoff takes backoff_percent off the next announcement, down to volume_floor — at the defaults, 5% a violation over five minutes, floored at a quarter as loud, so fifteen reach the bottom. The percentage is off what a listener hears rather than off the amplitude (how a volume is read). The first swear in a window is at full volume, and none of this affects the tally.

Past a point the sentence stops being said at all. After dampen_after fines in full inside a sliding dampen, a one-credit fine becomes the chime alone. This is off unless asked for: -1 is the default, and 0 dampens from the first one. A fine worth more than one credit is never dampened, though it does spend from the budget.

A dampened fine is still counted, still answers recall_triggers, and is still quietened by the backoff. It needs a chime — with none configured a dampened fine says nothing at all, which is reported at startup.

The announcements are rendered at startup, every name in users against one, two, and three violations in both wordings. Anyone not on the roster pays for their first fine, and nobody pays for it again.

chime is resolved inside SPEECH_DIR/chimes — a bare name or a path below it; anything that climbs out is refused at startup. It must be a 16-bit WAV, any sample rate, mono or stereo.

A server electing in with no words is enabled and listening for nothing, which is reported at startup.

Asking what it was

The announcement names the fine and never the word. Saying one of recall_triggers within recall of being fined is answered with the word, through recall_announcement — ten seconds by default, and that window is the whole gate. Outside it, and for anybody with no fine on record, nothing is said at all.

The answer is the last word of the fine that earned it, and it is the asker’s own. A fine that went unannounced can still be asked about, the word being recorded whether or not anybody heard the fine.

Three ways it parts company with the fine it is about: it carries no chime, it is not quietened by the backoff, and an utterance that both asks and offends is fined and not answered. Like a fine, it is dropped rather than queued while something is playing. It is also not rendered in advance, so the first answer naming a given word waits for the synthesizer.

Settings

The settings: block of config.yaml. Every one of these has a default, so none of them has to be written down; a name or a value that will not parse is reported at startup and falls back to the default.

Settings of the same name under different sections are unrelated. backoff means one thing under settings.quotes and another under settings.fines, and neither reads the other. The section is part of the name.

Spans of time

Every setting naming a span — a timeout, a backoff, a retention, a fade — carries its unit on the value rather than in its name, both here and in a tool’s own config.

A span can be turned off three ways, which mean the same thing and read differently depending on the setting: a word — forever, never, or immediately — 0, or a negative span like -1d. A retention of forever keeps everything; a backoff of never answers every time; a wait of immediately does not wait.

off and no are not among them. YAML reads both as booleans before the value is ever parsed, so a file that turns a window off that way is reported rather than obeyed.

settings.tts

Only used by tools that answer out loud. Where the synthesizer is is TTS_HOST and TTS_PORT, and which voice it uses is TTS_VOICE.

settings.credits

Only used by scoreboard. Where the tally is written down is CREDITS_FILE.

settings.fines

Only used by verbal-morality. What a fine is worth is the scoreboard’s; these are how it is said.

These are the deployment’s answer, and a server may write any of them in its own verbal-morality config instead, where it wins.

settings.quotes

Only used by quotes. The triggers and the lines themselves are a YAML file at QUOTES_FILE, plus whatever a server added for itself.

The deployment’s answer, which a server may override in its own quotes config, on the same terms as a fine: one room says the same six things all night and the next one does not.

settings.transcripts

Where transcripts are written is TRANSCRIPT_DIR, and what clock they are stamped with is TZ.

Pruning is off by default, and any value below 1 disables it entirely — 0 is a no-op rather than “delete everything”, so a mis-set setting cannot destroy the archive. At a positive N, files older than N days are deleted, aged by the date at the front of the filename rather than mtime. Pruning runs at startup and whenever a session opens.

Writing a window

A window is written as a day and a 24-hour range, and says when a session may start being written down — not how long it may run for. A session that opens inside one keeps writing until everybody disconnects, however far past the end.

schedule:
  - Wed 17:00-00:00      # Wednesday 17:00 until midnight
  - Fri 21:00-02:00      # Friday 21:00 until 02:00 Saturday

A schedule nothing could be read out of writes nothing down, rather than falling back to something wider. An entry that cannot be read is dropped and reported at startup, and if none survive, that room keeps nothing.

settings.presence

What the bot says about itself while a conversation is being kept. Per deployment and necessarily so: Discord has one presence per bot rather than one per server. See the status.

settings.llm

Only used by summary. Where the endpoint is, what key it wants, and which model to ask for are LLM_API_BASE, LLM_API_KEY, and LLM_MODEL.

On reasoning models

Two traps, both with a setting for a fix.

Reasoning is generated, so it spends max_output_tokens. Thinking and answer come out of the same budget, and running out mid-thought leaves content empty — a 200 carrying nothing, which reads like a broken endpoint and is a setting. Measured against a 27B reasoning model on a real 1,653-line session: 4,137 generated tokens, of which the answer was about 700. At 1024 it never reached the answer at all. The client says so rather than making you find out:

the model spent its whole 1024-token budget reasoning and never began the
answer. Raise 'settings.llm.max_output_tokens', or set
'settings.llm.thinking: false' to stop it reasoning at all

Reasoning is also most of the wall clock. That same session took 94s with reasoning and 12s without, for summaries of comparable quality. Nobody waits on a summary written after everyone has left, but somebody is waiting on the retelling — so a deployment pointing at a reasoning model wants thinking: false, for the sake of that one path.

Thinking is stripped whichever way it arrives, whether or not thinking: false is set, the setting being a request rather than a guarantee.

settings.summaries

Where summaries are written is SUMMARY_DIR.

Environment

What a deployment points at, rather than how it behaves. .env is loaded if present. Nothing about a particular deployment is baked into the image, so the same image runs anywhere the variables below point it at.

Discord

With AUTOJOIN enabled the bot connects as soon as a non-bot member enters a voice channel and disconnects once it empties of humans. A bot can occupy only one voice channel per guild, so a second channel becoming active does not make it hop — which would fragment both transcripts. !mq join and !mq leave remain available either way, and require Message Content Intent in the Discord Developer Portal.

ASR

TTS

Only used by tools that answer out loud. A deployment with no such tool enabled never opens a connection.

How a volume is read

Every volume in this bot is a knob rather than a multiplier: 1 is full, 0 is silent, and half is half as loud to listen to. That covers PLAYBACK_VOLUME, settings.fines.volume_floor, settings.fines.backoff_percent, and each channel’s hold_volume.

The setting is converted on a power-law curve on its way to the samples, which is why these numbers do what they say:

Volumes multiply as knobs, so a tool asking for half of a deployment set to half is announced at a quarter — a quarter as loud, which is a tenth of the amplitude. Nothing has to be set in decibels.

Quotes

Credits

LLM

Only used by summary. An OpenAI-compatible chat-completions endpoint and nothing more specific: a root, an optional bearer token, and a model name. /chat/completions is the whole of the API surface used, so a hosted API, a gateway in front of one, and a model on the next machine over are the same three variables.

Transcripts

Speech segmentation

VAD thresholds, the pre-roll depth, and the Wyoming chunk size are deliberately not configurable at all, from either place — they are tied to Silero’s fixed 512-sample frame and live in config.py.