# HH AI Agent

Агент автоматически ищет вакансии на HH.ru, оценивает их через LLM, генерирует сопроводительные письма и присылает подходящие в Telegram.

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

Запусти мастер настройки — он проведёт тебя через все шаги:

```bash
python setup_wizard.py
```

Wizard спросит:
1. Токен Telegram-бота и твой User ID
2. Какой AI-провайдер использовать (Ollama локально, Mistral API или любой OpenAI-compatible)
3. Данные твоего профиля для анализа вакансий
4. Режим работы (`dry_run`, `approval` или `auto`)

После этого создаст `.env` и `profile.yaml`, проверит конфигурацию и покажет что делать дальше.

**Изменить настройки позже:**

```bash
python setup_wizard.py --edit
```

---

## Требования

- Python 3.11+
- Telegram Bot (создаётся через [@BotFather](https://t.me/BotFather))
- Один из LLM-провайдеров (подробнее ниже)
- [CloakBrowser](https://cloakbrowser.com/) (устанавливается автоматически через wizard)

---

## Режимы работы

| Режим | Описание |
|---|---|
| `dry_run` | Ищет и анализирует вакансии, присылает превью в Telegram — **без реальных откликов** |
| `approval` | Присылает вакансию в Telegram с кнопкой «Откликнуться» для ручного подтверждения |
| `auto` (автоподача) | Автоматически откликается на вакансии с высоким совпадением (по умолчанию ≥ 85%) безопасными пачками по расписанию; остальные отправляет на ручной аппрув |

Начинай с `dry_run`. Переходи на `approval` или `auto` после того как убедишься что всё работает.

Карточка вакансии показывает краткое объяснение совпадения, рейтинг компании с HH и сворачиваемое сопроводительное письмо. Если rich messages недоступны, бот отправляет обычную HTML-карточку.

### Опциональная автоподача

Автоподача выключена по умолчанию. Для её включения нужны все три настройки:

```dotenv
APP_MODE=approval
ENABLE_REAL_APPLY=true
AUTO_APPLY_ENABLED=true
```

Порог совпадения, размер пачки, интервалы и рабочее окно задаются через `AUTO_APPLY_*` в `.env`. Агент соблюдает `MAX_APPLICATIONS_PER_DAY`, продолжает поиск до достижения фактического размера пачки и отправляет итог каждого запуска в Telegram. Вакансии ниже порога остаются на ручной проверке. Если состояние отправки нельзя подтвердить, circuit breaker приостанавливает следующие отклики.

---

## LLM-провайдеры

### Ollama (рекомендуется — локально, бесплатно)

1. Установи [Ollama](https://ollama.com/download)
2. Загрузи модель:
   ```bash
   ollama pull llama3
   ```
3. В wizard выбери **Ollama**

### Mistral API (облачный)

1. Зарегистрируйся на [console.mistral.ai](https://console.mistral.ai/)
2. Создай API ключ
3. В wizard выбери **Mistral API** и введи ключ

Wizard создаёт отдельный `MISTRAL_KEYS_MASTER_KEY` для локального шифрования ключей. Сохрани резервную копию этого значения: без него уже сохранённые ключи расшифровать нельзя. После запуска ключами можно управлять командой `/mistral_keys`; в Telegram и логах показываются только последние четыре символа.

> ⚠️ При Mistral текст вакансий и твой профиль уходят во внешний API.

### OpenAI-compatible (любой совместимый)

Поддерживается любой сервис с эндпоинтом `/chat/completions` (LocalAI, LM Studio, Groq и т.п.).
В wizard выбери **OpenAI-compatible** и укажи URL + ключ.

> При использовании облачного OpenAI-compatible провайдера текст вакансии и данные профиля передаются этому провайдеру.

---

## Telegram-команды

| Команда | Описание |
|---|---|
| `/start` | Краткая справка |
| `/status` | Режим, состояние, статистика |
| `/pause` | Приостановить поиск |
| `/resume` | Возобновить поиск |
| `/pending` | Вакансии, ожидающие решения |
| `/stats` | Статистика по статусам |
| `/diagnostics` | Результат последнего цикла и состояние circuit breaker |
| `/mistral_keys` | Список, проверка, добавление и удаление Mistral-ключей |
| `/cancel` | Отменить ввод CAPTCHA |

---

## Архитектура

| Файл | Ответственность |
|---|---|
| `config.py` | Валидация `.env` и `profile.yaml` |
| `browser_backend.py` | CloakBrowser / Playwright адаптер |
| `hh_client.py` | Поиск, чтение страниц, отправка откликов |
| `llm/` | Ollama / Mistral / OpenAI-compatible адаптеры, retry, квота |
| `ai_analyzer.py` | Анализ вакансий, генерация писем |
| `cover_letter.py` | Нормализация и обязательные проверки сопроводительного письма |
| `database.py` | SQLite-состояние, лимиты, переходы статусов |
| `approval.py` | Единственный разрешённый инициатор реального отклика |
| `tg_bot.py` | Telegram-команды, превью, inline-кнопки |
| `main.py` | Основной цикл агента |
| `instance_lock.py` | Защита от одновременного запуска двух процессов |
| `setup_wizard.py` | Интерактивный мастер настройки |

---

## Безопасность

- Реальный отклик требует `APP_MODE=approval` + `ENABLE_REAL_APPLY=true` и либо нажатия кнопки твоим Telegram ID, либо отдельно включённой автоподачи с достаточным confidence
- Автоподача выключена по умолчанию и ограничивается размером пачки, рабочим окном и дневным лимитом
- Ссылка на портфолио может быть объявлена обязательной; без неё письмо не будет отправлено
- После начала отправки неопределённый результат резервирует дневной слот и останавливает автоматическую серию, чтобы не создавать дубли
- `.env`, `profile.yaml` и `.browser-profile/` исключены из Git
- Токены, cookies и полный `.env` не записываются в логи

---

## Типичные ошибки

| Ошибка | Решение |
|---|---|
| `Configuration error` | Заполни все обязательные поля через `python setup_wizard.py --edit` |
| `CloakBrowser failed to start` | Проверь `python -m cloakbrowser info`, при необходимости смени на `BROWSER_BACKEND=playwright` |
| `HH.ru login is required` | Запусти с `BROWSER_HEADLESS=false` и войди вручную |
| `LLM check failed` | Проверь endpoint, ключ и дневную квоту через `python main.py --check-llm` |
| `Invalid model response` | Проверь провайдер и модель — вакансия безопасно пропускается |

---

## Разработка

Тесты не обращаются к HH.ru, Telegram или внешним LLM:

```bash
python -m compileall .
pytest -q
```

---

## Ограничения

- Автоматизация может нарушать правила HH.ru — ответственность за аккаунт несёт пользователь
- CloakBrowser не гарантирует отсутствие детектирования или CAPTCHA
- Нет proxy, GeoIP-ротации и внешних CAPTCHA-сервисов
- Рассчитано на одного владельца и одну SQLite-базу
- В ручном режиме письмо можно проверить и отредактировать в Telegram; автоподача отправляет его без предварительного просмотра

---

## Благодарности

Огромное спасибо **[kkonstantin08](https://github.com/kkonstantin08)** за разработку этой архитектуры — именно он спроектировал весь безопасный конвейер от поиска вакансий до approval-механизма с permit-токенами.

Также благодарность **[danscMax](https://github.com/danscMax)** — он реализовал базовые проверки и валидацию конфигурации, которые легли в основу надёжной работы агента.

Искренняя благодарность **[vadzhipov](https://github.com/vadzhipov)** (Azat Vadzhipov) — за проектирование и реализацию надёжного механизма автоподачи откликов (guarded auto-apply) с пакетированием, контролем порога совпадения, рабочим окном и защитой circuit breaker.

---

## Контакты

Вопросы и предложения: **@fikstt3 (telegram)**

## Disclamer: автоматизация HH.ru нарушает пользовательское соглашение, использовать на свой страх и риск. Автор не несет ответственность за возможные ограничения аккаунта.