No description
  • Elixir 93.1%
  • Nix 3.8%
  • Dockerfile 3.1%
Find a file
2026-09-02 20:30:31 +03:00
config Initial commit 2026-09-02 20:30:31 +03:00
deploy Initial commit 2026-09-02 20:30:31 +03:00
lib/markov_bot Initial commit 2026-09-02 20:30:31 +03:00
test Initial commit 2026-09-02 20:30:31 +03:00
.envrc Initial commit 2026-09-02 20:30:31 +03:00
.gitignore Initial commit 2026-09-02 20:30:31 +03:00
flake.lock Initial commit 2026-09-02 20:30:31 +03:00
flake.nix Initial commit 2026-09-02 20:30:31 +03:00
mix.exs Initial commit 2026-09-02 20:30:31 +03:00
mix.lock Initial commit 2026-09-02 20:30:31 +03:00
README.md Initial commit 2026-09-02 20:30:31 +03:00

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:

  1. lib/markov_bot/markov.ex — the model. Pure functions, no processes. Start here; it is the whole algorithm and none of the framework.
  2. lib/markov_bot/chat.ex — a GenServer wrapping one chain. Shows state, call vs cast, and terminate/2.
  3. lib/markov_bot/chat_supervisor.ex — a DynamicSupervisor plus Registry. This is where process-per-entity clicks.
  4. lib/markov_bot/application.ex — the supervision tree and why the child order is what it is.
  5. 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.exs asserts 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: :transient means an abnormal exit is restarted automatically, and init/1 reloads the chain from disk.

Exercises

Roughly in order of difficulty. Each one is a real change, not a toy.

  1. Watch it recover. Run iex -S mix, find a chat pid with Registry.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.
  2. :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.
  3. Order as a runtime setting. Make /order 3 rebuild a chat's chain. Forces you to think about what happens to existing data on a schema change.
  4. Backoff. The poller currently Process.sleeps 5s on failure, which blocks the process. Replace it with Process.send_after and exponential backoff, and notice why that is strictly better.
  5. Drop Storage from the tree and watch every Chat fail to start. Then change the supervisor strategy to :rest_for_one and reason about what changed.
  6. Prune the chain. Chains grow without bound. Add an LRU or count-based eviction and decide whether it belongs in Markov (pure) or Chat (lifecycle). The answer tells you if you have internalised the split.
  7. 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.