живая виртуальная девушка-компаньонка в telegram. своя личность, характер и вкусы, память, живое настроение и - главное - своё поведение: пишет первой, ревнует, обижается, скучает, придумывает ласковые прозвища, шлёт стикеры и голосовые. анимешница и геймерша: говорит про аниме/мангу/манхву/ранобэ/игры со своим мнением, качает мангу и ранобэ с *lib, знает цены и отзывы steam, гуглит, понимает картинки и даже комментирует твой экран.

• ведёт себя как настоящий человек: своё мнение, потребности, капризы. может не ответить, надуться, сама поделиться впечатлениями. говорит от первого лица, часто упоминает себя.
• типажи характера (режимы) - базовый тон личности, переключается на лету:
  • влюблённая (loving) · милашка/дередере (deredere) · цундере (tsundere)
  • яндере (yandere, художественный отыгрыш - только на словах) · куудере (kuudere)
  • отстранённая (distant) · игривая (playful)
• стадия отношений - влияет на близость тона: только познакомились → неделя → месяц → полгода → год → давно вместе.
• ревность двух видов: обижается, если долго молчишь, и ревнует к другим девушкам - если замечает соперницу в переписке, на присланной картинке или у тебя на экране (сила: soft / normal / strong).
• близость и пет-неймы: уровень близости копится со временем и разблокирует более тёплый тон и ласковые прозвища.
• энергия/батарейка: к ночи «устаёт», сообщения короче и мягче.
• обидки (sulk): может подуться после ссоры/долгого игнора, потом отходит.

• печатает по-человечески: индикатор «печатает…», паузы под скорость набора, дробит длинные ответы на несколько сообщений.
• эмодзи-реакции на твои сообщения, опечатки с самоисправлением (*то есть), «прочитала, но молчит пару минут».
• стикеры и кастом-эмодзи по настроению.
• голосовые сообщения (silero tts, опционально) - иногда отвечает голосом. (звучит ужасно, в следующих обновлениях обязательно подправлю!)
• настроение (mood): happy / sad / tired / excited / curious / annoyed / playful / loving / jealous - влияет на тон, плавно дрейфует и восстанавливается, залипает по-живому на пару часов.

• сама решает, когда написать первой - никаких окон по часам и лимитов: каждые ~20 мин смотрит на контекст и решает, хочет ли написать.
• смотрит на экран (screen watch): сама, по желанию, заглядывает на твой монитор и комментирует (нужен провайдер с vision).
• лента жизни: раз в день сама придумывает себе бытовое событие («досмотрела аниме», «ходила на пары»).
• возвращение: если тебя долго не было - встречает по-особому.
• памятные даты: в нужный день сама поздравит.
• погода-забота: «там у тебя дождь, возьми зонтик» (нужен ключ openweather и город).
• темы-хвосты: может вернуться к тому, о чём вы говорили раньше.

ai сама вызывает нужный инструмент в tool-loop:

• web_search, google_search - поиск в интернете
• anime_search, anime_info, anime_tracking - аниме со своим мнением + трекинг
• lib_search, lib_info, lib_download - mangalib / ranobelib / hentailib: манга/ранобэ/хентай в pdf / cbz / epub / txt кнопками (выбор тайтла, глав и формата; упавшие главы пропускаются, а не рвут докачку)
• steam_search, steam_game, steam_reviews - цены/скидки с реакцией и угарные отзывы (кнопки «другая игра / ещё отзыв»)
• memory_save - сохранить важный факт
• image_vision - понимает присланные картинки
• weather - погода
• request_api_key - сама попросит недостающий ключ, когда он нужен

• агентная схема: telegram → ai core → tool-loop → tools (anime, *lib, steam, web, weather, memory, vision).
• единый интерфейс провайдеров: gemini · openai · claude · deepseek · ollama · yandex · g4f (gpt4free - бесплатно, без ключей).
• быстрый g4f: кэш последней рабочей пары (провайдер+модель), параллельная гонка бэкэндов с забором первого успешного, жёсткие таймауты и отсев дохлых.
• ollama: может сам поставить/запустить/подтянуть локальную модель.
• личность в бд: имя, возраст, характер, стиль, речь, интересы, эмоциональность - редактируется /set.
• умная память: llm-экстрактор вытаскивает важные факты и достаёт их по релевантности.
• устойчивая сеть: авто-восстановление подключения - при обрыве связи с telegram (частый «превышен таймаут семафора» на windows / при блокировках) бот сам пересоздаёт сессию и переподключается, ручной перезапуск не нужен. при желании можно пустить трафик через прокси (TELEGRAM_PROXY, поддержка socks5).

стек: python 3.12, aiogram 3, sqlalchemy 2 (async), redis (опционально), pillow + mss (скриншоты), silero (голос).

git clone https://github.com/elytrya/mahiru-ai mahiru && cd mahiru
# или распакуй архив с проектом

python setup_wizard.py

мастер проведёт по шагам прямо в консоли:

1. telegram - BOT_TOKEN (@botfather) и твой ADMIN_IDS (@userinfobot).
2. ai-провайдер - g4f (бесплатно, без ключей) / gemini / openai / claude / deepseek / yandex (с ключом и <Я не могу обсуждать эту тему. Давайте поговорим о чём-нибудь ещё>) / ollama (локально).
3. база данных - sqlite (файл) / postgresql / custom.
4. google search - опционально (без него не полезет в интернет).
5. поведение / очеловечивание - печатает, паузы, реакции и т.п.
6. характер - типаж (влюблённая, цундере, яндере…) и стадия отношений.
7. инициатива - как часто может писать первой.
8. экран - разрешить ли смотреть на монитор.

в конце мастер сам предложит pip install -r requirements.txt и запуск python bot.py. если запустить python bot.py без .env - бот сам предложит мастер.

готово (* ^ ω ^)

личность · память · ai/провайдер · человечность · ** типаж и стадия** (режим характера, стадия отношений, ревность к соперницам) · статистика · очистка · экспорт. всё меняется без перезапуска.

xtekky/gpt4free агрегирует публичные бэкэнды в единый api - ключи не нужны.

• G4F_MODEL - deepseek-v3, gpt-4o-mini, gpt-4o, claude-3-5-sonnet и др.
• G4F_PROVIDER - принудительный бэкэнд (пусто → auto).
• сменить на лету: /admin → Провайдер.

публичные бэкэнды нестабильны - таймауты и ошибки нормальны. для стабильности лучше платный ключ.

mahiru/
├─ bot.py                  # entry point: first-run check + супервизор с авто-реконнектом
├─ setup_wizard.py         # интерактивная настройка
├─ config.py               # pydantic Settings (все параметры .env)
├─ .env.example            # шаблон конфигурации с комментариями
├─ ai/
│  ├─ core.py              # AI Core с tool-loop
│  ├─ prompts.py           # системный промпт: личность, типаж, стадия, ревность
│  ├─ personality.py       # модель личности
│  ├─ mood.py              # настроение и его дрейф
│  ├─ sulk.py              # обидки
│  ├─ threads.py           # темы-хвосты (возврат к разговору)
│  ├─ context.py           # сборка контекста
│  └─ providers/           # gemini | openai | claude | deepseek | ollama | yandex | g4f
├─ memory/                 # analyzer + storage + manager
├─ methods/                # tools: anime, lib, steam, web, google, weather, memory, image, api_keys
├─ handlers/               # aiogram: messages, admin, callbacks, lib_download, steam_flow
├─ scheduler/              # автономная инициатива
├─ db/                     # SQLAlchemy модели и репозиторий
└─ utils/                  # logger, cache, humanize, screen, stickers, voice, weather, settings_kv

# methods/my_tool/hello.py
from methods.base import Tool

class HelloTool(Tool):
    name = "hello"
    description = "Сказать привет"
    parameters = {"type": "object",
                  "properties": {"name": {"type": "string"}},
                  "required": ["name"]}

    async def run(self, args, *, session, user_id: int):
        return {"reply": f"Привет, {args['name']}!"}

зарегистрируй в methods/registry.py - ai сама вызовет, когда потребуется.

создай ai/providers/my.py, наследуй BaseProvider, реализуй chat(), добавь в REGISTRY в ai/providers/factory.py. всё.

gpl-3.0