Add README and update CLAUDE.md with project docs

2026-02-22 23:00:23 +02:00 · 2026-02-22 23:00:23 +02:00 · 8a84145e15
commit 8a84145e15
parent ec1112e162
2 changed files with 141 additions and 1 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,104 @@
+# Telegram Channel Analyzer Bot
+
+Telegram bot that analyzes public channels using Claude AI. Fetches channel history via Telethon, chunks messages, summarizes with Claude, and delivers a report back in Telegram.
+
+## Report Types
+
+- **Content Analysis** — topics, tone, themes, content strategy
+- **Content + Stats** — above + posting frequency, engagement patterns
+- **Full Audit** — all above + sentiment, audience insights, recommendations
+
+## Prerequisites
+
+- Telegram Bot token from [@BotFather](https://t.me/BotFather)
+- Telegram API credentials from [my.telegram.org](https://my.telegram.org)
+- Anthropic API key from [console.anthropic.com](https://console.anthropic.com)
+- Docker or Podman
+
+## Setup
+
+```bash
+cp .env.example .env
+# Edit .env with your credentials
+```
+
+`.env` values (no inline comments):
+```
+BOT_TOKEN=123456:ABC...
+TELEGRAM_API_ID=12345678
+TELEGRAM_API_HASH=abc123def456...
+TELEGRAM_PHONE=+1234567890
+ANTHROPIC_API_KEY=sk-ant-...
+CLAUDE_MODEL=claude-haiku-4-5
+```
+
+Available models: `claude-opus-4-6`, `claude-sonnet-4-6`, `claude-haiku-4-5`
+
+## Run with Docker
+
+```bash
+# Build
+docker build -f Containerfile -t tg-analyzer .
+
+# First run: interactive login to create Telethon session
+docker run -it --env-file .env -v ./data:/app/data tg-analyzer python -m bot --login
+
+# Run the bot
+docker run -d --env-file .env -v ./data:/app/data --name tg-analyzer --restart unless-stopped tg-analyzer
+```
+
+## Run with Podman
+
+```bash
+# Build
+podman build -t tg-analyzer .
+
+# First run: interactive login
+podman run -it --env-file .env -v ./data:/app/data tg-analyzer python -m bot --login
+
+# Run the bot
+podman run -d --env-file .env -v ./data:/app/data --name tg-analyzer tg-analyzer
+```
+
+## Run with Compose
+
+```bash
+# Login first (see above), then:
+podman compose up -d
+# or
+docker compose up -d
+```
+
+## Usage
+
+Send to your bot in Telegram:
+
+```
+/analyze @channel_username
+```
+
+Select a report type from the inline keyboard. The bot will show progress as it fetches and analyzes.
+
+## Project Structure
+
+```
+bot/
+├── __main__.py          # Entrypoint: aiogram + Telethon on shared loop
+├── config.py            # pydantic-settings from env vars
+├── models.py            # ReportType enum, ChannelMessage dataclass
+├── handlers/
+│   ├── start.py         # /start, /help
+│   └── analyze.py       # /analyze + report type selection + progress
+├── services/
+│   ├── fetcher.py       # Telethon: read channel history
+│   ├── chunker.py       # Token-bounded message chunking
+│   ├── analyzer.py      # Claude API: chunk summaries → synthesis
+│   └── formatter.py     # Split report into Telegram-safe HTML messages
+└── prompts/
+    ├── chunk_summary.py # Per-chunk extraction prompts
+    └── synthesis.py     # Final synthesis prompts
+```
+
+## Rate Limits
+
+The bot respects Anthropic API rate limits with automatic retry and cooldown between chunks. On the free/low tier (30K input tokens/min), a large channel may take several minutes.