# 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`