i-Lang/TelegramGuard

<div align="center">

🛡️ antispam.bot

The AI guardian that keeps your Telegram groups clean — and actually answers your questions.

Open source (MIT), zero config, self-hostable — the TelegramGuard project.

   

🌐 English · 中文 · Русский · Español · العربية · فارسی

</div>

Add it to your group (zero setup)

Add the official bot — no install, no config, no cost.

→ @iLangGuardBot

1. 1.Search @iLangGuardBot on Telegram
2. 2.Add it to your group
3. 3.Give it admin — delete messages + ban users
4. 4.Done. Spam is cleaned automatically; @ it anytime with a question.

You can also DM it directly for AI chat.

What it does

🚫 Anti-Spam — Catches ads, scams, crypto & gambling spam. Sees through Unicode lookalikes, full-width and zero-width tricks, emoji stuffing and slang. A zero-cost pre-filter kills the obvious stuff before it ever reaches the AI, and repeat-flooding is caught with no AI call at all.

👁️ Vision — Reads images and video thumbnails to catch image-based ads and QR-code scams. In chat, it reads the story behind a photo, not just the pixels.

💬 Chat — @ it in any group or DM it privately. Multilingual, auto-detects your language. Ask it anything and get a clear, useful answer — factual on sensitive topics, with sensible boundaries on genuinely harmful ones.

Self-Host

Bring any OpenAI-compatible AI provider — SiliconFlow (default), OpenAI, DeepSeek, or a local model. You need two things:

• —Bot Token — @BotFather → /newbot
• —AI API Key — from your provider (default targets SiliconFlow)

Option 1 — VPS (one command)

curl -sL https://raw.githubusercontent.com/ilang-ai/TelegramGuard/main/install.sh | sudo bash

Clones, installs dependencies, prompts for your two keys, and runs as a systemd service. Manage it with:

systemctl status telegramguard     # status
systemctl restart telegramguard    # restart
journalctl -u telegramguard -f     # live logs

Option 2 — HuggingFace Space (free, no server)

1. 1.Fork this repo
2. 2.Create a HuggingFace Space → Docker SDK → Blank
3. 3.GitHub repo → Settings → Secrets → add HF_TOKEN (your HF write token)
4. 4.HF Space → Settings → Secrets → add BOT_TOKEN + AI_API_KEY
5. 5.HF Space → Settings → enable persistent storage so /data (the SQLite DB) is writable — or add a DB_PATH secret pointing somewhere writable
6. 6.Push to GitHub — it auto-deploys to the Space

Option 3 — Manual

git clone https://github.com/ilang-ai/TelegramGuard.git
cd TelegramGuard
pip install -r requirements.txt
cp .env.example .env         # fill in BOT_TOKEN + AI_API_KEY
set -a; source .env; set +a  # load .env into the environment
python bot.py

After creating your bot, send to @BotFather: /setjoingroups → Enable and /setprivacy → Disable (so it can see group messages).

Configuration

Everything is set via environment variables — see `.env.example`:

Customize the AI

The bot's brain lives in plain .ilang files — I-Lang Prompt Spec, where each ::GENE defines a behavior.

prompts_demo/
├── persona.ilang     how it thinks + how it talks
├── antispam.ilang    what counts as spam
└── vision.ilang      how it reads images

::GENE_IMMUTABLE{S002, T:RUTHLESS_RED_TEAM, A:FLATTER⇒FAIL, G:ALL, Θ:ALWAYS}
# Show it a plan and it hunts the fatal flaw instead of praising.

::GENE_MUTABLE{P002, T:CONCISE, G:ALL, Θ:ALWAYS}
# 2-3 sentences. Answer first, detail after, zero filler.

::IMMUNE{SPAM, DETECT_THEN_NUKE}
# Ads / scams / flooding → delete + strike, see through evasion.

Change the genes, change the bot. To customize: copy prompts_demo/ to prompts/ (loaded first) and edit.

[Learn I-Lang Prompt Spec →](https://ilang.ai/spec/)

Architecture

TelegramGuard/
├── bot.py                 Entry — handlers (group · private · events)
├── config.py              Env config
├── install.sh             One-command VPS installer
├── Dockerfile             Container build
├── modules/
│   ├── ai_provider.py     OpenAI-compatible AI layer (text · vision · audio)
│   ├── chat.py            Prompt orchestration (loads .ilang)
│   ├── prefilter.py       Zero-cost spam pre-filter + triage
│   ├── lexicon.py         Slang / evasion normalization + scoring
│   ├── probe.py           Check-in filler detection (mark-only, never bans)
│   ├── ilang_judge.py     I-Lang decision function
│   ├── admin.py           Group admin
│   ├── db.py              Shared SQLite + async lock
│   └── database.py        Schema
└── prompts_demo/          AI personality (.ilang files)

<div align="center">

Built with [I-Lang Prompt Spec](https://ilang.ai) — structured AI instructions as genetic code.

  

MIT · © iLang Inc. · antispam.bot · ilang.ai

</div>

Citation

CITATION.cff; Zenodo archives each release. Concept DOI 10.5281/zenodo.22865154 (all versions).