Sergei Poljanski
c30b7e4675
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
58 lines
3.2 KiB
Markdown
58 lines
3.2 KiB
Markdown
# 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`
|