.env.example

# ── Telegram ──────────────────────────────────────────────────────────────
# Bot token from @BotFather. Required.
TELEGRAM_TOKEN=
# Group username (public) or numeric ID (private). Legacy, prefer TELEGRAM_GROUPS.
TELEGRAM_GROUP=
# Multiple groups (comma-separated IDs or usernames). Overrides TELEGRAM_GROUP if set.
TELEGRAM_GROUPS=
# HTTP timeout for Telegram API calls. Default: 30s
TELEGRAM_TIMEOUT=30s
# Idle duration before sending startup message. Default: 30s
TELEGRAM_IDLE=30s

# ── Admin ────────────────────────────────────────────────────────────────
# Admin chat ID for spam reports and moderation controls.
ADMIN_GROUP=
# Disable treating forwarded messages in admin chat as spam.
DISABLE_ADMIN_SPAM_FORWARD=false
# Super-users: immune to bans, can use /spam, /ban, /warn, /unban.
# Mix of usernames (without @) and numeric IDs, comma-separated.
SUPER_USER=

# ── Server / Web UI ─────────────────────────────────────────────────────
# Enable HTTP server for web UI and JSON API.
SERVER_ENABLED=false
# Listen address. Default: :8080
SERVER_LISTEN=:8080
# Separate port for /healthz and /readyz probes. Empty = disabled.
SERVER_PROBE_LISTEN=
# Basic auth password for user "tg-spam". "auto" = random, printed on startup.
SERVER_AUTH=auto
# bcrypt hash of the password (more secure than SERVER_AUTH).
SERVER_AUTH_HASH=

# ── OpenAI ───────────────────────────────────────────────────────────────
# API token. Enables text + vision checks when set.
OPENAI_TOKEN=
# Custom API base URL (e.g. proxy or compatible provider). Empty = official API.
OPENAI_API_BASE=
# Model name. Use gpt-4o for vision support. Default: gpt-4o-mini
OPENAI_MODEL=gpt-4o-mini
# Veto mode: true = OpenAI confirms spam only when other checks flag it first.
# false = OpenAI checks messages not caught by other checks. Default: false
OPENAI_VETO=false
# Custom system prompt. Empty = built-in default.
OPENAI_PROMPT=
# Additional spam patterns to check (comma-separated).
OPENAI_CUSTOM_PROMPT=
# Max tokens in API response. Default: 1024
OPENAI_MAX_TOKENS_RESPONSE=1024
# Max tokens in API request. Default: 2048
OPENAI_MAX_TOKENS_REQUEST=2048
# Max symbols in request (fallback if tokenizer fails). Default: 16000
OPENAI_MAX_SYMBOLS_REQUEST=16000
# Retry count on API errors. Default: 1
OPENAI_RETRY_COUNT=1
# Number of previous messages as context. 0 = no context. Default: 0
OPENAI_HISTORY_SIZE=0
# Reasoning effort for thinking models: none, low, medium, high. Default: none
OPENAI_REASONING_EFFORT=none
# Check messages shorter than --min-msg-len. Default: false
OPENAI_CHECK_SHORT_MESSAGES=false
# Vision model for image analysis. Empty = same as OPENAI_MODEL.
# Use when the text model doesn't support vision (e.g. local LLM + cloud vision).
OPENAI_VISION_MODEL=

# ── Gemini ───────────────────────────────────────────────────────────────
# API token. Enables text + vision checks when set.
GEMINI_TOKEN=
# Model name. Default: gemma-4-31b-it
GEMINI_MODEL=gemma-4-31b-it
# Veto mode (same behavior as OPENAI_VETO).
GEMINI_VETO=false
# Custom system prompt.
GEMINI_PROMPT=
# Additional spam patterns (comma-separated).
GEMINI_CUSTOM_PROMPT=
# Max tokens in response. Default: 1024
GEMINI_MAX_TOKENS_RESPONSE=1024
# Max symbols in request. Default: 8192
GEMINI_MAX_SYMBOLS_REQUEST=8192
# Retry count. Default: 1
GEMINI_RETRY_COUNT=1
# Context history size. Default: 0
GEMINI_HISTORY_SIZE=0
# Check short messages. Default: false
GEMINI_CHECK_SHORT_MESSAGES=false
# Vision model for slow-path image analysis. Empty = GEMINI_MODEL.
GEMINI_VISION_MODEL=

# ── LLM consensus ───────────────────────────────────────────────────────
# When multiple LLMs are eligible: "any" = any flips decision, "all" = all must agree.
LLM_CONSENSUS=any
# Timeout per LLM request. Default: 30s
LLM_REQUEST_TIMEOUT=30s
# Minimum trimmed characters for automatic LLM checks. Force checks bypass this. Default: 5
LLM_MIN_INPUT_CHARS=5

# ── Classifier ──────────────────────────────────────────────────────────
# Spam similarity threshold (0-1). 1.0 = disabled. Default: 0.5
SIMILARITY_THRESHOLD=0.5
# Min message length to check. 0 = check all. Default: 50
MIN_MSG_LEN=50
# Min spam probability (%) to ban. Default: 50
MIN_PROBABILITY=50
# Max emojis in message. -1 = disabled, 0 = any emoji = spam. Default: 2
MAX_EMOJI=2
# Words mixing multiple languages to flag as spam. 0 = disabled. Default: 0
MULTI_LANG=0
# Check all messages, not just first. Default: false
PARANOID=false
# Number of first messages to check per user. Default: 1
FIRST_MESSAGES_COUNT=1

# ── Meta checks ─────────────────────────────────────────────────────────
# Flag images with text shorter than min-msg-len.
META_IMAGE_ONLY=false
# Max links in message. -1 = disabled. Default: -1
META_LINKS_LIMIT=-1
# Flag messages with links but no text.
META_LINKS_ONLY=false
# Max @mentions. -1 = disabled. Default: -1
META_MENTIONS_LIMIT=-1
# Flag videos with short text.
META_VIDEO_ONLY=false
# Flag audio with short text.
META_AUDIO_ONLY=false
# Flag shared contacts with no text.
META_CONTACT_ONLY=false
# Flag forwarded messages.
META_FORWARD=false
# Flag messages with inline keyboards.
META_KEYBOARD=false
# Prohibited symbols in username (e.g. "@#$").
META_USERNAME_SYMBOLS=
# Flag giveaway messages.
META_GIVEAWAY=false

# ── Behavioral checks ───────────────────────────────────────────────────
# Duplicate messages to trigger spam. 0 = disabled. Default: 0
DUPLICATES_THRESHOLD=0
# Time window for duplicate tracking. Default: 1h
DUPLICATES_WINDOW=1h

# Abnormal spacing detection.
SPACE_ENABLED=false
SPACE_RATIO=0.3
SPACE_SHORT_RATIO=0.7
SPACE_SHORT_WORD=3
SPACE_MIN_WORDS=5

# ── Moderation ──────────────────────────────────────────────────────────
# First strike: mute/restrict duration. Default: 30m
MODERATION_FIRST_STRIKE=30m
# Second strike: mute/restrict duration. Default: 6h
MODERATION_SECOND_STRIKE=6h
# Soft ban: restrict instead of kick. User stays in group but can't send.
SOFT_BAN=false
# Delete all recent messages from user on /spam or /ban.
AGGRESSIVE_CLEANUP=false
# Max messages to delete in aggressive cleanup. Default: 100
AGGRESSIVE_CLEANUP_LIMIT=100
# Don't reply "this is spam" in the group.
NO_SPAM_REPLY=false
# Delete join message when user is kicked.
SUPPRESS_JOIN_MESSAGE=false
# Delete all join messages immediately.
DELETE_JOIN_MESSAGES=false
# Delete all leave messages immediately.
DELETE_LEAVE_MESSAGES=false

# ── User reporting ──────────────────────────────────────────────────────
REPORT_ENABLED=false
# Reports needed for admin notification. Default: 2
REPORT_THRESHOLD=2
# Auto-ban after N reports (0 = disabled, must be >= threshold).
REPORT_AUTO_BAN_THRESHOLD=0
# Max reports per user per period. Default: 10
REPORT_RATE_LIMIT=10
# Rate limit period. Default: 1h
REPORT_RATE_PERIOD=1h

# ── Messages ────────────────────────────────────────────────────────────
# Message sent to group on bot startup. Empty = no message.
MESSAGE_STARTUP=
# Response when spam detected.
MESSAGE_SPAM=this is spam
# Response in dry mode.
MESSAGE_DRY=this is spam (dry mode)
# Warning message on /warn.
MESSAGE_WARN=You've violated our rules and this is your first and last warning.

# ── Logging ─────────────────────────────────────────────────────────────
LOGGER_ENABLED=false
LOGGER_FILE=tg-spam.log
LOGGER_MAX_SIZE=100M
LOGGER_MAX_BACKUPS=10

# ── Storage ─────────────────────────────────────────────────────────────
# Database URL: SQLite file path or postgres://user:pass@host:port/dbname.
DB=tg-spam.db
# Dynamic data directory (samples, database, etc).
FILES_DYNAMIC=data
# Storage operation timeout. 0 = no timeout.
STORAGE_TIMEOUT=0s
# Sample migration: enabled, disabled, only. Default: enabled
CONVERT=enabled
# Auto-backup count on version upgrade. 0 = disabled. Default: 10
MAX_BACKUPS=10

# ── History ─────────────────────────────────────────────────────────────
# How long to keep messages for /spam lookup. Default: 24h
HISTORY_DURATION=24h
# Min messages to keep even if duration expired. Default: 1000
HISTORY_MIN_SIZE=1000
# History size for similarity check. Default: 100
HISTORY_SIZE=100

# ── Retention ───────────────────────────────────────────────────────────
RETENTION_ENABLED=false
RETENTION_INTERVAL=1h
RETENTION_INCIDENTS_TTL=720h
RETENTION_APPEALS_TTL=720h
RETENTION_DETECTED_SPAM_TTL=720h
RETENTION_INCOMING_EVENTS_TTL=168h
RETENTION_MODERATION_ACTIONS_TTL=720h
RETENTION_LABELS_TTL=720h
RETENTION_CANDIDATES_TTL=720h
RETENTION_USAGE_COUNTERS_TTL=168h

# ── Lua plugins ─────────────────────────────────────────────────────────
LUA_PLUGINS_ENABLED=false
# Directory with .lua plugin files.
LUA_PLUGINS_PLUGINS_DIR=
# Only load these plugins (comma-separated, without .lua). Empty = all.
LUA_PLUGINS_ENABLED_PLUGINS=
# Auto-reload plugins on file change.
LUA_PLUGINS_DYNAMIC_RELOAD=false

# ── Modes ───────────────────────────────────────────────────────────────
# Training mode: detect but don't ban or delete.
TRAINING=false
# Dry run: log actions but don't execute bans/deletes.
DRY=false

# ── Debug ───────────────────────────────────────────────────────────────
DEBUG=false
# Verbose Telegram library logging.
TG_DEBUG=false
# Instance identifier. Relevant only for multi-instance setups.
INSTANCE_ID=tg-spam