CI Telegram Technical report License: MIT

"Beer is proof that God loves us and wants us to be happy." (Benjamin Franklin)

BeerEX is a rule-based expert system, available as a Telegram bot, that suggests a beer to drink according to your taste and meal. It reasons over a knowledge base of beer styles built from authoritative craft-beer sources, and can explain why it asks each question and how it reached every recommendation.

It was developed during the Knowledge Engineering course @ University of Bari "Aldo Moro" (prof. Floriana Esposito) and revised during the Artificial Intelligence Fundamentals course @ University of Pisa.

The knowledge base is built from CraftBeer.com material (published by the Brewers Association): the 2017 Beer Styles Study Guide and the Beer & Food Course.

• Two reasoning backends, switchable at runtime (/cf · /fuzzy):
  • Certainty Factors — the classic MYCIN-style evidence combination;
  • Fuzzy logic — data-grounded membership functions (colour↔SRM, alcohol↔ABV, bitterness↔IBU) derived from real style data, scored with a reusable pure-CLIPS fuzzy library.
• Comprehensive, data-grounded knowledge base mined from the CraftBeer guides: per-style numeric ranges (ABV/IBU/SRM/OG/FG/CO2), qualitative profile (palate, hop, malt, serving temperature, glassware) and authoritative food pairings (cheese / entrée / dessert).
• Transparent, per-beer explanations ("pale colour μ1.00, high bitterness μ0.50, matches its CraftBeer pairing").
• Reusable fuzzy library — dmeoli/FuzzyCLIPS, fuzzy logic written in pure CLIPS, validated against the original FuzzyCLIPS engine, vendored here as a git submodule.
• Modern, async Telegram bot (python-telegram-bot v21) with one isolated CLIPS environment per chat (safe under concurrency), Docker image and CI.
• Optional localization (gettext-style): English is the base; an Italian overlay is selectable with /en · /it and falls back to English where untranslated.

 Telegram bot (async) / CLIPS CLI
 │ one CLIPS env per user
 ▼
 dialogue ── questions ──► best-* evidence ──► selection backend
 (dialog.clp) (beer-questions) (beer-knowledge) ├─ cf : combine-CFs
 └─ fuzzy : membership + scoring
 │ (beer-fuzzy.clp + FuzzyCLIPS)
 ▼
 top beers + data-grounded explanation + serving info

git clone --recurse-submodules https://github.com/DonatoMeoli/BeerEX.git
cd BeerEX
cp .env.example .env # put your @BotFather TOKEN in .env
docker compose up --build

git submodule update --init # fetch the fuzzy library
python3.12 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
export TOKEN=<your-telegram-bot-token>
python BeerEX.bot.py

Use Python 3.12: clipspy and python-telegram-bot do not support 3.13+ yet.

/cf, /fuzzy, /en and /it take effect on the next /new. English is always the base; Italian is an overlay that falls back to English where untranslated.

The bot needs no system CLIPS (clipspy bundles it), but the CLI does:

bash scripts/build-clips.sh # builds CLIPS 6.4.2 into ~/.local/bin
clips -f BeerEX.clp

make test # engine smoke test over clipspy (no token needed)
make test-clips # the CLIPS test suite (needs the clips 6.4.x CLI)

The reusable fuzzy library carries its own differential tests against the original FuzzyCLIPS engine (third_party/FuzzyCLIPS/tests/diff_test.sh).

GitHub can't host a long-running bot, but CI publishes the image to GHCR (ghcr.io/dmeoli/beerex); run it on any small host (VPS, Fly.io, Railway, a Raspberry Pi) with docker run or docker compose up.

Released under the MIT License. See the LICENSE file for details.