AnalyzerTGChat

🇬🇧 English | 🇷🇺 Русский

Инструмент, который берёт обычную переписку в Telegram и вытаскивает из неё неожиданно много: кто и как менялся за годы, чьи шутки вошли в фольклор, какие эпохи пережила компания, кто с кем сблизился, а кто отдалился.

Работает в три шага: экспортирует чат через Telegram API → нарезает на удобные для ИИ куски → отдаёт Claude, который пишет отчёт по каждому периоду, а затем сводит всё в одну большую «летопись компании».

Отчёты выходят на удивление меткие и тёплые — с цитатами-жемчужинами, портретами участников, языковыми отпечатками («любимые слова», «фирменные эмодзи») и хроникой главных событий. После прочтения хочется перечитать заново и переслать остальным.

Только не показывайте отчёт человеку, который не готов узнать о себе слишком много 🙂

---

Возможности:

• Экспорт истории любого чата (личного, группы, канала) в CSV.
• Статистика слов: ТОП слов по всему чату и по каждому участнику — сохраняется в data/stats/<chat>.md.
• Подготовка для ИИ: чистка, склейка, разбиение на части по периодам. Каждый чат — в свою подпапку data/parts/<chat>/.
• Анализ через Claude: каждая часть прогоняется отдельно (быстро/дёшево, с prompt caching), затем собирается единый финальный отчёт. Отчёты пишутся в data/reports/<chat>/.
• HTML-рендер: рядом с каждым .md автоматически создаётся .html со светлой/тёмной темой. Можно открыть в браузере двойным кликом и удобно почитать. Если понадобится пересобрать все HTML разом (правили .md руками, обновили стиль и т.п.) — это делается одной строкой из консоли:

python -c "from tg_analyzer.config import Config; from tg_analyzer.html_render import render_all; render_all(Config.from_env())"

---

1. Установка

Требуется Python 3.10+.

Вариант А: одной командой (Windows)

1. Скачайте/склонируйте репозиторий.
2. Дважды кликните run.bat. Он:
   • создаст файл .env из .env.example (заполните его);
   • создаст виртуальное окружение .venv;
   • установит зависимости из requirements.txt;
   • запустит main.py.

Вариант Б: одной командой (Linux/macOS)

chmod +x run.sh
./run.sh

Вариант В: вручную

python -m venv .venv
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate

pip install -r requirements.txt
cp .env.example .env   # потом отредактируйте .env
python main.py

---

2. Настройка .env

Скопируйте .env.example в .env и заполните значения.

Telegram API (для экспорта)

1. Зайдите на https://my.telegram.org со своим Telegram-аккаунтом.
2. Откройте раздел API development tools.
3. Создайте «приложение» (любое имя/описание).
4. Скопируйте App api_id и App api_hash в .env:

API_ID=12345678
API_HASH=abcdef0123456789abcdef0123456789

Claude API (для анализа)

1. Получите ключ на https://console.anthropic.com.
2. Положите его в .env:

ANTHROPIC_API_KEY=sk-ant-...

Если используете прокси/гейтвэй с Anthropic-совместимым API — измените ANTHROPIC_BASE_URL.

Остальные параметры (опционально)

Переменная	По умолчанию	Что делает
MIN_LEN	3	Минимальная длина слова в статистике
TOP_N	30	Размер ТОП-списка слов и участников
MAX_CHARS_PER_PART	250000	Целевой размер части при разделении (в символах)
MERGE_BURSTS_MINUTES	0	Склеивать подряд идущие сообщения одного автора (мин). 0 = не склеивать
MIN_TEXT_LEN	1	Сообщения короче этого выкидываются
NORMALIZE_LAUGHTER	False	Сворачивать «ахаха»/«пхпхпх» к короткому виду
MODEL_PARTS	claude-sonnet-4-6	Модель для анализа отдельных частей
MODEL_FINAL	claude-opus-4-7	Модель для финального синтеза
PARALLEL_WORKERS	4	Сколько частей анализировать параллельно
SPLIT_BY	quarter	quarter или month — стратегия разделения

---

3. Запуск

python main.py

Откроется меню:

============================================================
   AnalyzerTGChat — анализ Telegram-чатов
============================================================
1. Экспортировать чат из Telegram
2. Статистика слов по CSV-экспорту (сохранение в .md + HTML)
3. Разделить CSV на части для ИИ
4. Проанализировать части через Claude (+ финальный отчёт)
5. Полный пайплайн (1 → 3 → 4)
6. Только финальный отчёт (пересобрать из готовых part_*.md)
0. Выход
============================================================

При первом запуске пункта 1 Telegram попросит код подтверждения (придёт в самом Telegram). Сессия сохранится в data/telegram_session.session — повторно код вводить не нужно.

---

4. Структура проекта

AnalyzerTGChat/
├── main.py                  # точка входа
├── requirements.txt
├── .env.example             # шаблон конфигурации
├── .gitignore
├── run.bat / run.sh         # обёртки запуска
├── prompts/                 # шаблоны промптов для ИИ
│   ├── company_context.md   # ОТРЕДАКТИРУЙТЕ под свою компанию
│   ├── part_analysis.md     # промпт для анализа части
│   └── final_report.md      # промпт для финального синтеза
├── tg_analyzer/             # пакет с логикой
│   ├── config.py            # загрузка/валидация .env
│   ├── prompts.py           # чтение шаблонов
│   ├── exporter.py          # экспорт чата
│   ├── stats.py             # статистика слов
│   ├── splitter.py          # разделение на части
│   ├── analyzer.py          # анализ через Claude
│   └── ui.py                # меню
└── data/                    # появится после первого запуска
    ├── exports/             # CSV-экспорт чатов (chat_export_<title>_<ts>.csv)
    ├── stats/               # <chat_slug>.md + .html — статистика слов
    ├── parts/
    │   └── <chat_slug>/     # part_*.txt + index.md/participants.md/stats.json
    ├── reports/
    │   └── <chat_slug>/     # part_*.md + final_report.md (+ .html рядом)
    ├── telegram_session.session
    └── .last_chat.json      # последний выбранный чат

`<chat_slug>` соответствует имени CSV-файла без префикса `chat_export_`,
поэтому несколько разных чатов не смешиваются между собой при анализе.

---

5. Кастомизация промптов

Если вы хотите получить более точный анализ — обязательно отредактируйте:

• prompts/company_context.md — короткое описание компании, период, ключевые имена. Этот текст подставится во все промпты ИИ.
• prompts/part_analysis.md — что должно быть в отчёте по одной части.
• prompts/final_report.md — структура финального отчёта.

После правки промптов запустите пункт 4 заново. Готовые part_*.md пропускаются — удалите их вручную из data/reports/, если хотите перепроанализировать всё с новым промптом.

---

6. Частые проблемы

API_ID и API_HASH не заданы в .env — заполните .env, см. раздел 2.

PEER_ID_INVALID при экспорте — Telegram вас не знает с этим чатом. Используйте list (выбор из диалогов) или username.

max_tokens упёрлось — финальный отчёт обрезан. Увеличьте MAX_TOKENS_FINAL в .env. Или уменьшите длину входа: уменьшите MAX_CHARS_PER_PART или используйте SPLIT_BY=month.

Долгий запрос «висит» — анализ части может занимать несколько минут. Скрипт использует streaming, ничего не падает по 10-минутному таймауту.

Прерывание работы — анализ можно остановить (Ctrl+C). При следующем запуске уже готовые part_*.md пропускаются.

---

⭐ Понравился проект?

Поставьте звёздочку! Это лучший способ сказать «спасибо», и благодаря этому проект найдут другие люди, которым он тоже может быть полезен.

Нашли баг или есть идея? Открывайте issue или присылайте PR — буду рад.