# KAndrusyak Bot

Telegram-ассистент с двумя режимами AI: локальными Ollama + faster-whisper или
облачными YandexGPT + SpeechKit через Yandex AI Studio,
контекстом текущего диалога,
долговременной памятью, заметками, напоминаниями и отслеживанием статусов.

Вся переписка сохраняется в SQLite отдельно для каждого чата. В текущий контекст попадают
последние реплики активной темы, причем более свежие сообщения имеют больший приоритет.
При явной смене темы модель начинает новый контекст, не удаляя архив. К старому обсуждению
можно вернуться обычной просьбой к боту или найти сообщения командой `/history ключевые слова`.
Команда `/new` вручную начинает новую тему и также сохраняет предыдущую переписку.

## Структура

- `main.py` — совместимая точка входа;
- `assistant_bot/application.py` — сборка Telegram-приложения;
- `assistant_bot/config.py` — переменные окружения и настройки;
- `assistant_bot/storage.py` — SQLite-хранилище;
- `assistant_bot/ollama.py` — HTTP-клиент Ollama;
- `assistant_bot/yandex_ai.py` — адаптер Yandex AI Studio SDK;
- `assistant_bot/agent.py` — агентный цикл и выполнение внутренних tools;
- `assistant_bot/agent_tools.py` — единый реестр и исполнители agent tools;
- `assistant_bot/services.py` — типизированный контейнер сервисов приложения;
- `assistant_bot/handlers.py` — Telegram-команды и сообщения;
- `assistant_bot/reminders.py` — разбор времени напоминаний;
- `assistant_bot/jobs.py` — фоновые задачи;
- `assistant_bot/migrations.py` — версионируемые миграции SQLite;
- `tests/` — модульные тесты ядра.

## Запуск

```powershell
conda activate kandrusyak_bot
python -m pip install -r requirements.txt
python main.py
```

Также пакет можно запустить командой `python -m assistant_bot`.

Обязательная настройка в `.env`:

```dotenv
BOT_TOKEN=...
ASSISTANT_PASSWORD=...
ASSISTANT_MODE=local
```

`ASSISTANT_PASSWORD` — общий пароль доступа к боту. Новый пользователь должен
один раз отправить его боту в личном чате; после успешной проверки авторизация
сохраняется в SQLite, а сам пароль в базу данных не записывается.

`ASSISTANT_MODE` принимает `local` (значение по умолчанию) или `yandex`.
Общие дополнительные настройки: `ASSISTANT_DB`, `ASSISTANT_TIMEZONE` и
`VOICE_MAX_DURATION_SECONDS`.

### Локальный режим

В режиме `local` текст обрабатывает Ollama, а голосовые сообщения распознаются
локально через faster-whisper. Настройки:

```dotenv
ASSISTANT_MODE=local
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=qwen3.5:9b
```

При первом голосовом сообщении модель faster-whisper будет загружена
автоматически. Настройки распознавания:

```dotenv
WHISPER_MODEL=large-v3
WHISPER_DEVICE=cuda
WHISPER_COMPUTE_TYPE=int8
WHISPER_LANGUAGE=ru
VOICE_MAX_DURATION_SECONDS=120
```

По умолчанию используется полная модель `large-v3` на NVIDIA GPU с вычислениями INT8
и beam size 5. Крупная модель сохраняет приоритет качества, а INT8 уменьшает расход
видеопамяти. Для этого режима необходимы CUDA 12, cuBLAS для CUDA 12 и cuDNN 9.
Чтобы определять язык автоматически, укажите `WHISPER_LANGUAGE=auto`.

На Windows используется зафиксированная версия CTranslate2 4.6.0: более новые
сборки 4.7.x могут аварийно завершаться при инициализации модели. Проект настроен
для Conda-окружения `kandrusyak_bot`. Полный набор DLL cuDNN 9 должен находиться
в системном `PATH` или рядом с библиотекой CTranslate2.

### Режим Yandex AI Studio

В режиме `yandex` бот использует официальный Yandex AI Studio SDK: YandexGPT для
текста и SpeechKit для Telegram-аудио в формате OGG Opus. Создайте API-ключ с
необходимыми ролями и укажите стандартные переменные авторизации SDK:

```dotenv
ASSISTANT_MODE=yandex
YANDEX_CLOUD_FOLDER=...
YC_API_KEY=...
YANDEX_CLOUD_MODEL=yandexgpt/latest
YANDEX_STT_MODEL=general
YANDEX_STT_LANGUAGE=ru-RU
VOICE_MAX_DURATION_SECONDS=120
```

`YANDEX_CLOUD_FOLDER` — идентификатор каталога Yandex Cloud (например, значение
вида `b1g...`), а не имя модели. Имя и версия модели указываются отдельно в
`YANDEX_CLOUD_MODEL`, например `qwen3.6-35b-a3b/latest`.

Значения моделей можно посмотреть командой `/models`, а пользовательский выбор
сохранить командой `/model имя-модели`. Выбор хранится отдельно для локального и
облачного режимов. Короткое имя облачной модели автоматически преобразуется в URI
`gpt://<YANDEX_CLOUD_FOLDER>/<YANDEX_CLOUD_MODEL>`.

## Docker

Один `Dockerfile` содержит два независимых target. Облачный Yandex-образ является
target по умолчанию и не содержит CUDA, faster-whisper и CTranslate2:

```bash
docker build --target yandex -t kandrusyak-bot:yandex .
docker run -d \
  --name kandrusyak-bot \
  --restart unless-stopped \
  --env-file .env \
  -e ASSISTANT_MODE=yandex \
  -v kandrusyak-data:/data \
  kandrusyak-bot:yandex
```

Локальный образ содержит CUDA 12, cuDNN 9 и faster-whisper. Для него требуется
NVIDIA Container Toolkit:

```bash
docker build --target local -t kandrusyak-bot:local .
docker run -d \
  --name kandrusyak-bot \
  --restart unless-stopped \
  --gpus all \
  --env-file .env \
  -e ASSISTANT_MODE=local \
  -v kandrusyak-data:/data \
  kandrusyak-bot:local
```




Ollama должна быть доступна контейнеру по адресу из `OLLAMA_BASE_URL`; адрес
`localhost` внутри контейнера указывает на сам контейнер, а не на Linux-хост.

## Проверка

```powershell
conda activate kandrusyak_bot
python -m unittest discover -v
```

Для локальных проверок качества установите dev-зависимости:

```powershell
python -m pip install -r requirements-common.txt -r requirements-dev.txt
python -m ruff check .
python -m coverage run -m unittest discover -v
python -m coverage report
```