Telegram bot that streams OpenRouter chat responses in real-time with per-user history stored in SQLite.

• Real-time streaming: AI responses stream token-by-token, editing the same Telegram message
• Multi-user support: Each user has isolated conversation history
• Unlimited conversation storage: All messages saved to SQLite, context clipped for model limits
• Model selection: Choose from OpenRouter's live model list per session or set a default
• Multi-turn conversations: Full conversation history maintained per user
• Commands: /start, /help, /clear, /model, /setdefault

• Python 3.13+
• uv package manager
• Telegram Bot Token (get from @BotFather)
• OpenRouter API Key (get from openrouter.ai)

1. Clone the repository
2. Install dependencies:

uv sync --all-groups

1. Copy .env.example to .env:

cp .env.example .env

2. Edit .env and set your API keys:

TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
OPENROUTER_API_KEY=your_openrouter_api_key_here
DATABASE_PATH=./bot_data.db
APP_NAME=Telebot
DEBUG=false

uv run python main.py

• /start - Register and see welcome message
• /help - Show available commands
• /clear - Start a new conversation (previous history remains in DB)
• /model - Choose a model for the current session
• /setdefault - Set your default model (saved to DB)

uv run ruff check .

uv run mypy .

• main.py - Entry point, initializes bot and runs polling
• bot/config.py - Configuration loader from environment
• bot/database.py - SQLite async database layer (users, conversations, messages, preferences)
• bot/client.py - OpenRouter API client with SSE streaming
• bot/handlers.py - Telegram command and message handlers
• bot/utils.py - Utilities for rate limiting, message splitting, and context clipping

• users: user_id, username, default_model
• conversations: conversation_id, user_id, created_at
• messages: message_id, conversation_id, role, content, model_used, created_at
• preferences: user_id, preference_key, preference_value

• Storage: Unlimited message history stored in SQLite
• Context window: Messages clipped to ~20k characters for model input
• Rate limiting: Edits throttled to avoid Telegram API limits (200ms intervals)
• Message splitting: Long responses automatically split at 4096 char limit
• Streaming: Responses edited in real-time as tokens arrive from OpenRouter