AI Personal Assistant (Telegram Bot)

Проект представляет собой многокомпонентного AI-агента в виде Telegram-бота, разработанного в рамках тестового задания. Агент выступает в роли личного помощника, способного управлять задачами и календарем пользователя, искать информацию в интернете и отвечать на вопросы, используя собственную базу знаний.

📸 Скриншоты

🎯 Назначение агента

Личный помощник (Personal Assistant). Его основная задача — помогать пользователю в организации его дня и быстром поиске информации, интегрируясь с его персональными сервисами (Google Calendar, Google Tasks).

✨ Основные возможности

• 📅 Управление календарем: Просмотр событий на день, неделю, а также создание новых событий в Google Calendar.
• ✅ Управление задачами: Просмотр списка активных дел и добавление новых задач в Google Tasks.
• 🌐 Поиск в интернете: Поиск актуальной информации и формирование кратких ответов на основе найденных данных.
• 🧠 База знаний: Способность отвечать на вопросы о самом себе, своей архитектуре и целях проекта, используя RAG (Retrieval-Augmented Generation).
• 💬 Контекст диалога: Агент помнит предыдущие сообщения в рамках сессии для ведения осмысленного диалога.

🏗️ Архитектура: "Agent-Tool Gateway"

Проект построен на микросервисной архитектуре, где компоненты изолированы и взаимодействуют по сети внутри Docker. Это обеспечивает надежность, масштабируемость и четкое разделение ответственности.

+-------------------------------------------------+      +-------------------------------------------+
|              🤖 Сервис: agent_app                |      |            🛠️ Сервис: mcp_server            |
|                                                 |      |                                           |
| +-----------+   +----------------+   +--------+ |      | +-----------+      +--------------------+ |
| |           |   |                |   |        | |      | |           |----->| Google Calendar/Tasks| |
| | Telegram  |-->|  LangChain     |-->|  MCP   | |----->| | MCP Server|      +--------------------+ |
| | Interface |   |  Agent Core    |   | Client | |      | | (FastMCP) |----->|   Tavily Search    | |
| | (Aiogram) |   |  (llama3:8b)   |   |        | |      | |           |      +--------------------+ |
| +-----------+   +----------------+   +--------+ |      | +-----------+                               |
|       ^               |                         |      +-------------------------------------------+
|       | (Память)      | (База знаний)           |
|       v               v                         |
| +-----------+   +----------------+              |
| |           |   |                |              |
| |   Redis   |   |    ChromaDB    |              |
| |           |   |                |              |
| +-----------+   +----------------+              |
+-------------------------------------------------+

• agent_app: "Мозг" системы. Принимает сообщения от Telegram, управляет памятью (Redis) и базой знаний (ChromaDB), запускает LangChain-агента для принятия решений и обращается к mcp-server для выполнения действий.
• mcp_server: "Руки" системы. Предоставляет внешние инструменты (Google API, Web Search) по стандартизированному протоколу Model Context Protocol (MCP). Этот сервис инкапсулирует всю логику работы с внешними API, включая аутентификацию.
• ollama: Локальный сервер для запуска LLM (llama3:8b).
• redis: Хранилище для кратковременной памяти диалогов (сессий).

💡 Особенности и ограничения локальной LLM

Важной особенностью проекта является использование полностью локальной, open-source языковой модели (llama3:8b) вместо коммерческих API (таких как OpenAI GPT). Это обеспечивает полную приватность данных и независимость от внешних сервисов, но также накладывает определенные ограничения:

• Скорость ответа: Локальная модель, работающая на CPU, значительно медленнее облачных аналогов. Ответ на сложный запрос может занимать от 30 секунд до нескольких минут.
• Качество "мышления": Модель llama3:8b — мощная для своего размера, но может иногда ошибаться в выборе инструмента или "зацикливаться" (для этого предусмотрен max_iterations). Она менее надежна, чем флагманские модели вроде GPT-4.
• Требования к ресурсам: Для запуска стека требуется значительный объем RAM (рекомендуется 16 ГБ и более), так как модель загружается в оперативную память.

Этот выбор является осознанным компромиссом между производительностью и полной автономностью системы.

🛠️ Технологический стек

• Язык: Python 3.11
• AI/ML:
  • LLM: llama3:8b (запускается через Ollama)
  • Оркестрация агента: LangChain
  • Векторная база: ChromaDB
  • Модель эмбеддингов: sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
• Backend & API:
  • Telegram-интерфейс: Aiogram 3.x
  • Протокол инструментов: mcp-sdk (Model Context Protocol)
  • Веб-сервер для MCP: FastAPI (встроен в mcp-sdk)
• Базы данных: Redis (для памяти диалогов)
• DevOps: Docker, Docker Compose

🔌 Используемые MCP-инструменты

Агент использует три внешних инструмента, предоставляемых через mcp-server:

1. Google Calendar API: Для чтения и создания событий в календаре.
2. Google Tasks API: Для чтения и создания задач в списках дел.
3. Tavily Search API: Для поиска актуальной информации в интернете.

🧠 Реализация памяти и базы знаний

• Память диалога (кратковременная): Реализована с помощью ConversationBufferWindowMemory из LangChain. История сообщений для каждого пользователя хранится в Redis под уникальным ключом (user_id), что обеспечивает персистентность сессий.
• База знаний (долговременная): Реализована на базе ChromaDB. Текстовые документы из папки knowledge_base/ при первом запуске преобразуются в векторы (эмбеддинги) и сохраняются на диск. Агент использует эту базу через Retriever Tool для ответов на вопросы о самом проекте (RAG).

🚀 Установка и запуск

Предварительные требования

• Git
• Docker (рекомендуется выделить не менее 8 ГБ RAM в настройках Docker Desktop)
• Docker Compose

1. Клонирование репозитория

git clone https://github.com/your-username/personal-assistant.git
cd personal-assistant

2. Настройка Google API

Это самый важный ручной шаг для доступа к Google Calendar и Tasks.

1. Перейдите в Google Cloud Console и создайте новый проект.
2. Включите API: Google Calendar API и Google Tasks API.
3. Настройте "Окно запроса доступа OAuth":
   • Тип пользователя: Внешнее.
   • На следующих шагах добавьте свой Google-аккаунт в "Тестовые пользователи".
4. Создайте учетные данные:
   • Нажмите "Создать учетные данные" -> "Идентификатор клиента OAuth".
   • Тип приложения: "Настольное приложение" (Desktop App).
   • Нажмите "Создать" и скачайте JSON-файл.
5. Переименуйте скачанный файл в credentials.json и поместите его в папку mcp_server/. Этот файл уже есть в .gitignore, поэтому он не попадет в Git.

3. Настройка переменных окружения

1. Скопируйте пример файла .env.example:

   cp .env.example .env

2. Откройте файл .env и вставьте свои реальные токены:
   • TELEGRAM_BOT_TOKEN: Получите у @BotFather в Telegram.
   • TAVILY_API_KEY: Получите после регистрации на Tavily.com.

4. Первая аутентификация Google

Этот шаг нужно выполнить один раз, чтобы получить token.json для доступа к вашему аккаунту Google.

# Убедитесь, что у вас установлен Python 3.11+
python3 -m venv venv
source venv/bin/activate  # для Linux/macOS
# venv\Scripts\activate   # для Windows

# Устанавливаем зависимости локально ТОЛЬКО для этого шага
pip install -r requirements.txt

# Запускаем скрипт аутентификации
python3 mcp_server/auth.py

• В консоли появится ссылка. Скопируйте ее, вставьте в браузер.
• Войдите в свой Google-аккаунт и предоставьте разрешения.
• Google выдаст вам код. Скопируйте его и вставьте обратно в консоль.
• В папке mcp_server/ должен появиться файл token.json.

5. Сборка и запуск Docker-контейнеров```bash

Собираем образы с нуля, игнорируя кэш (самый надежный способ)

docker-compose build --no-cache

Запускаем все сервисы в фоновом режиме

docker-compose up -d

6. Загрузка LLM

Выполните команду в терминале, чтобы скачать модель llama3:8b внутрь контейнера ollama. Это может занять некоторое время и потребует ~4.7 ГБ свободного места.

docker-compose exec ollama ollama pull llama3:8b

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

docker-compose restart research_agent

Ваш ассистент готов к работе!

💬 Как использовать

1. Найдите вашего бота в Telegram по имени, которое вы ему дали.
2. Начните диалог с команды /start.
3. Используйте команды /help и /health для получения информации и проверки статуса.
4. Задавайте вопросы на естественном языке:
   • Какая цель этого проекта?
   • Добавь задачу 'Купить молоко'
   • Какие у меня задачи?
   • Что у меня на завтра?
   • Создай событие 'Встреча с командой' завтра в 15:00
   • Какие последние новости про Apple?

📚 Справочная информация

• Model Context Protocol (MCP): Официальная документация протокола.
• Python SDK для MCP: Репозиторий библиотеки, которую мы использовали для создания MCP-сервера и клиента.
• LangChain: Фреймворк для создания приложений на базе LLM.
• Aiogram: Фреймворк для создания Telegram-ботов.
• Ollama: Инструмент для локального запуска LLM.

📂 Структура проекта

.
├── agent_app/          # "Мозг" - сервис агента
│   ├── agent.py        # Ядро агента (LangChain, LLM, инструменты)
│   ├── bot.py          # Логика Telegram-бота (Aiogram)
│   ├── db.py           # Управление векторной базой ChromaDB
│   ├── memory.py       # Управление памятью диалогов в Redis
│   └── main.py         # Точка входа для сервиса agent_app
├── mcp_server/         # "Руки" - сервис инструментов
│   ├── auth.py         # Логика аутентификации Google OAuth 2.0
│   ├── tools.py        # Функции-обертки для внешних API
│   └── main.py         # Сборка MCP-сервера (FastMCP)
├── knowledge_base/     # Документы для базы знаний
├── conversations/      # Логи общения с Cursor IDE
├── .env                # Файл с секретами (в .gitignore)
├── .env.example        # Шаблон для .env
├── .gitignore
├── docker-compose.yml  # Оркестрация всех сервисов
└── README.md           # Этот файл```

✒️ Разработка в Cursor

Весь код проекта написан и отлажен с использованием AI-ассистента в IDE Cursor. История взаимодействия с AI (промпты, сгенерированный код, помощь в отладке) сохранена в папке /conversations.