family-bot — семейный органайзер в Telegram

Telegram-бот-календарь для двоих: общее расписание, поездки и список мест «куда сходить». Пишете обычным текстом или голосом — бот сам разбирает фразу через Claude и раскладывает по записям. События зеркалятся в календарь iCloud (двусторонний синк), билеты и приглашения распознаются с фото и PDF.

Что умеет

• Свободный текст и голос. «завтра в 18 забрать Машу из садика», «каждый вторник в 19 йога», «занятия с 9 до 13». Голос распознаётся локально (faster-whisper) — данные не покидают сервер.
• Разделы: события (event) с датой/временем и места (place) без даты.
• Повторы (день/неделя/2 недели/месяц), интервалы («с 9 до 13»), мультидобавление («вт с 9, ср и пт с 10 — секция сына» → отдельная запись на каждый день).
• Просмотр и поиск: «что сегодня», «расписание», «когда у сына врач?».
• Правки и отмена: «перенеси зубного на пятницу 16:00», «удали 7», «оставь только полёт», «не верно / отмени» — откат последнего действия.
• Несколько команд в одной фразе — «удали выезд, а событие назови "отдых" и прикрепи ссылку».
• Файлы: билет (PDF/фото) → сразу поездка; приглашение/запись к врачу/афиша → черновик с подтверждением.
• iCloud CalDAV: события появляются на айфонах (общий календарь «Семья»); правки и новые события из календаря подхватываются обратно.
• Напоминания: утренняя сводка в 8:00 и пуш перед событием, если попросили явно.
• Доступ — только для первых MAX_USERS (по умолчанию 2), кто написал боту.
• Чистый чат — бот убирает лишние сообщения и держит одно актуальное окно (/classic отключает).

Требования

• Python 3.11+
• Claude CLI — установлен и авторизован (бот вызывает claude -p для разбора сообщений).
• Зависимости из requirements.txt.

Быстрый старт

git clone https://github.com/<you>/family-bot.git
cd family-bot
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env      # впишите TG_TOKEN (и, при желании, iCloud)
set -a && source .env && set +a
python -m familybot

Первые два человека, написавшие боту, привязываются автоматически.

Конфигурация — через переменные окружения, см. .env.example. Секретов в коде нет.

Структура

familybot/
├── __main__.py          # точка входа: long-polling + запуск фоновых потоков
├── config.py            # переменные окружения и константы
├── db.py                # SQLite: схема, миграции, key-value состояние
├── timeutil.py          # время, форматирование дат, окна today/tomorrow/week
├── help_text.py         # текст /help
├── access.py            # привязка пользователей и контроль доступа
├── ui.py                # клавиатуры, уведомление напарника, reply-ссылки
├── files.py             # разбор присланных файлов и черновики событий
├── handlers.py          # обработка сообщений, интентов, батчей и колбэков
├── scheduler.py         # утренняя сводка, напоминания, перекат повторов
├── telegram/            # слой Telegram Bot API
│   ├── api.py           #   сырые вызовы, загрузка файлов/голосовых
│   └── chat.py          #   TypingLoop, рассылка, «чистый чат», reply/push
├── ai/                  # понимание через Claude
│   ├── claude.py        #   запуск claude CLI, извлечение JSON
│   ├── prompts.py       #   промпты (текст/файлы/черновик)
│   ├── context.py       #   контекст записей для разбора ссылок
│   ├── parser.py        #   parse_intent / analyze_file
│   └── voice.py         #   распознавание голоса (faster-whisper)
├── items/               # записи календаря
│   ├── repository.py    #   CRUD, поиск, дедуп, снапшоты для отмены
│   └── render.py        #   форматирование записей и списков
└── calendar_sync/       # синк с iCloud
    ├── ics.py           #   сборка VEVENT
    ├── client.py        #   CalDAV-подключение, очередь отправки
    └── reconcile.py     #   двусторонняя сверка БД ↔ iCloud

Подробнее — docs/ARCHITECTURE.md и docs/DEPLOY.md.

Лицензия

MIT — см. LICENSE.