- Elixir 93.1%
- Nix 3.8%
- Dockerfile 3.1%
| config | ||
| deploy | ||
| lib/markov_bot | ||
| test | ||
| .envrc | ||
| .gitignore | ||
| flake.lock | ||
| flake.nix | ||
| mix.exs | ||
| mix.lock | ||
| README.md | ||
markov_bot
A Telegram bot that learns the voice of a chat with a Markov chain and talks back in it. Built as a vehicle for learning Elixir/OTP, so the structure is chosen for what it teaches as much as for what it does.
Quick start
direnv allow # or: nix develop
mix deps.get
mix test
To actually run it, get a token from @BotFather:
export TELEGRAM_BOT_TOKEN=123456:ABC-your-token
iex -S mix
Without a token the app still boots — the poller is simply not started — so tests and the REPL work offline.
In a group chat, disable privacy mode via BotFather (/setprivacy → Disable),
otherwise the bot only receives messages that mention it and will never learn
anything.
Commands
| Command | Effect |
|---|---|
/gen |
Say something |
/gen <word> |
Start from that word |
/stats |
What the chain has learned |
Ordinary messages are training data. The bot also answers unprompted with
probability :reply_chance (default 5%), which is the entire personality knob.
Reading order
The modules are worth reading in this sequence — each one adds exactly one OTP idea to the previous:
lib/markov_bot/markov.ex— the model. Pure functions, no processes. Start here; it is the whole algorithm and none of the framework.lib/markov_bot/chat.ex— aGenServerwrapping one chain. Shows state,callvscast, andterminate/2.lib/markov_bot/chat_supervisor.ex— aDynamicSupervisorplusRegistry. This is where process-per-entity clicks.lib/markov_bot/application.ex— the supervision tree and why the child order is what it is.lib/markov_bot/poller.ex— the I/O edge,handle_continue, and the single-replica constraint.
The design decision worth stealing
The model is a pure module and the process is a thin shell around it.
That split is why markov_test.exs can exercise the entire algorithm with no
supervision tree, no mocks and no async weirdness, while chat_test.exs tests
only lifecycle: restart, isolation, recovery.
When people say OTP code is easy to test, this is the shape they mean. The
temptation is to put the chain logic inside the GenServer callbacks; resist
it and both halves stay simple.
Process-per-chat
Each Telegram chat gets its own MarkovBot.Chat process, addressed by chat id
through a Registry. Consequences worth internalising:
- Isolation. A crash while training on one chat's malformed message cannot
touch another chat's model.
chat_test.exsasserts this by killing one process and checking its neighbour still answers. - No locks. Each chain is mutated by exactly one process, so there is no shared mutable state and nothing to synchronise.
- Cheap. A BEAM process is ~300 words of memory. Ten thousand idle chats cost less than one JVM thread pool.
- Free supervision.
restart: :transientmeans an abnormal exit is restarted automatically, andinit/1reloads the chain from disk.
Exercises
Roughly in order of difficulty. Each one is a real change, not a toy.
- Watch it recover. Run
iex -S mix, find a chat pid withRegistry.lookup(MarkovBot.Registry, chat_id),Process.exit(pid, :kill), then look it up again. Note what survived and what did not, and connect that to@flush_interval. :observer.start()in the REPL. Look at the Applications tab: the supervision tree is drawn for you. Kill a node in the tree by hand.- Order as a runtime setting. Make
/order 3rebuild a chat's chain. Forces you to think about what happens to existing data on a schema change. - Backoff. The poller currently
Process.sleeps 5s on failure, which blocks the process. Replace it withProcess.send_afterand exponential backoff, and notice why that is strictly better. - Drop
Storagefrom the tree and watch everyChatfail to start. Then change the supervisor strategy to:rest_for_oneand reason about what changed. - Prune the chain. Chains grow without bound. Add an LRU or count-based
eviction and decide whether it belongs in
Markov(pure) orChat(lifecycle). The answer tells you if you have internalised the split. - Second bot, same VM. Add a second token and a second poller under the same tree. This is the thing that makes BEAM cheaper than one container per bot.
Configuration
| Key | Env var | Default | Meaning |
|---|---|---|---|
:token |
TELEGRAM_BOT_TOKEN |
— | Bot token; poller is skipped when unset |
:order |
— | 2 |
Tokens of context (1 = noise, 3+ = parroting) |
:reply_chance |
MARKOV_REPLY_CHANCE |
5 |
Percent chance of an unprompted reply |
:data_dir |
MARKOV_DATA_DIR |
priv/data |
Where the DETS file lives |
Deployment note
getUpdates allows one open connection per bot token — a second poller
gets HTTP 409. So deploy/deployment.yaml pins replicas: 1 with
strategy: Recreate; a rolling update would briefly run two pollers and both
would error. See deploy/README.md.