Sergei Poljanski c30b7e4675 Add multi-user features: i18n, payments, multi-model AI, focus areas

Replace single report type with composable analysis: depth levels
(basic/standard/full) + focus area multi-select (psychology, business,
marketing, content, audience, sentiment). Multi-step inline keyboard
flow guides users through selection.

- i18n: English + Russian, auto-detect from Telegram, /lang override
- AI providers: Anthropic + OpenRouter via AIClient abstraction
- Telegram Stars payments with per-depth pricing and free trial
- SQLite (aiosqlite) for users, analyses, payments tracking
- User middleware for auto-registration and language detection
- Report persistence: save .md locally, offer file download
- New commands: /features, /prices, /lang
- Composable prompt system: depth modifiers + focus area fragments

2026-02-23 01:18:12 +02:00

3.2 KiB

Raw Permalink Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

Telegram Channel Analyzer Bot — multi-user public bot with payments, multi-language (EN/RU), multi-provider AI (Anthropic + OpenRouter). Fetches public channel history via Telethon, analyzes with configurable AI models (chunked summarization pipeline), delivers HTML reports via aiogram bot.

Stack

Python 3.12, async throughout
aiogram 3 — Telegram bot interface (commands, inline keyboards, payments, progress messages)
Telethon — userbot client for reading public channel history
anthropic (AsyncAnthropic) — Claude API with streaming
httpx — OpenRouter API calls (transitive dep of anthropic)
aiosqlite — SQLite database for users, usage, payments
pydantic-settings — config from environment variables

Architecture

Both aiogram and Telethon share one asyncio loop (no threads)
Telethon client is attached to the bot instance in __main__.py
Analysis flow: Channel → Depth selection → Focus areas (multi-select) → Model → Payment check → Pipeline
Pipeline: Fetch → Chunk (token-bounded) → Summarize each chunk → Synthesize final report → Save .md → Send
Rate limit handling: semaphore(1), 60s cooldown between chunks, retry with backoff on 429
Output: Markdown→HTML conversion, split on section boundaries at 4000 chars
User middleware auto-creates DB user, detects language, injects lang/db_user into handler data
In-memory _sessions dict tracks multi-step analysis flow per user

Key Files

bot/config.py — all settings from env vars (Anthropic, OpenRouter, pricing, paths)
bot/models.py — Depth, FocusArea enums, AnalysisSession dataclass
bot/i18n/ — Lang enum, t() lookup, all UI strings in strings.py
bot/db/ — aiosqlite engine, user_repo, usage_repo
bot/middleware/user_middleware.py — auto-create user, detect lang
bot/services/ai_client.py — AIClient ABC, AnthropicClient, OpenRouterClient, get_ai_client()
bot/services/analyzer.py — orchestrates chunk analysis + synthesis with retry
bot/services/report_saver.py — saves .md to data/reports/
bot/prompts/ — composable prompts: depth.py, focus_areas.py, chunk_summary.py, synthesis.py
bot/handlers/analyze.py — multi-step flow (depth→focus→model→pay→run)
bot/handlers/payment.py — pre_checkout handler

Running

Container-based: Containerfile + compose.yml
--login flag for interactive Telethon session creation
Session persists in data/ volume, DB at data/bot.db, reports at data/reports/
.env file must not have inline comments (Podman/Docker limitation)

Common Tasks

To change chunk size: edit MAX_TOKENS_PER_CHUNK in bot/services/chunker.py
To add a focus area: add to FocusArea enum, add prompt fragments in prompts/focus_areas.py, add i18n strings
To add an AI model: add to AVAILABLE_MODELS env var (use org/model format for OpenRouter)
To change pricing: set PRICE_BASIC/PRICE_STANDARD/PRICE_FULL env vars
To change free trial count: set FREE_ANALYSES env var
To add a language: add to Lang enum, add translations in i18n/strings.py

3.2 KiB Raw Permalink Blame History