MentorMatch

MentorMatch — платформа для управления программой наставничества с интеграцией Telegram и Google Sheets. Проект объединяет несколько FastAPI‑сервисов, административную панель, Telegram‑бота и модуль интеллектуального матчинга на базе LLM и эмбеддингов.

Ключевые возможности

• Импорт и синхронизация данных о студентах, наставниках, ролях и темах из Google Sheets.
• Управление заявками, подтверждениями и уведомлениями через Telegram‑бота и админ‑панель.
• Подбор кандидатов с использованием эмбеддингов (pgvector) и LLM (через прокси API) с fallback‑логикой.
• Хранение и выдача файлов (CV, мотивационных писем) через единое медиахранилище.
• Полностью контейнеризованная инфраструктура: FastAPI‑сервисы, Telegram‑бот, PostgreSQL+pgvector, pgAdmin.

Архитектура

Google Sheets --> google_data service --> Postgres (pgvector)
                                |
Telegram Bot <--> bot service --+
                                |
                            server API <--> matching service --> LLM API (proxy)
                                |
                             admin UI (FastAPI + Jinja)

docker-compose.yml поднимает все компоненты и общие тома для данных (pgdata, pgadmin_data, media_data).

Сервисы docker-compose

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

1. Установите Docker 24+ и docker compose v2.
2. Скопируйте шаблон переменных и заполните обязательные поля:

   cp env.example .env
   

   Минимально необходимы:
   • POSTGRES_PASSWORD
   • PROXY_API_KEY (ключ к прокси OpenAI API)
   • TELEGRAM_BOT_TOKEN
   • SPREADSHEET_ID
   • SERVICE_ACCOUNT_FILE (обычно service-account.json)
3. Поместите JSON сервисного аккаунта в google_data/service-account.json и выдайте ему доступ к нужным Google Sheets.
4. Запустите инфраструктуру:

   docker compose up -d --build
   

5. Проверьте сервисы:
   • API: http://localhost:8000/docs
   • Админка: http://localhost:8100
   • Telegram‑бот: вебхук должен указывать на BOT_API_URL (по умолчанию http://bot:5000)
   • pgAdmin (опционально): http://localhost:8080 (postgres / 5432 / mentormatch / secret)

Контейнер postgres автоматически применит schema.sql. Для полного пересоздания БД используйте docker compose down -v.

Переменные окружения

Дополнительно доступны настройки прокси Telegram (TELEGRAM_*), файлового логирования (LOG_FILE) и параметры модели.

Интеграция с Google Sheets

• Поделитесь таблицами с сервисным аккаунтом (e-mail из JSON).
• Основные операции:
  • POST /api/import/students (google_data) — студенты и их предпочтения.
  • POST /api/import/supervisors (google_data) — наставники и роли.
  • POST /api/import-sheet (server) — универсальный импорт листа по имени.
  • POST /api/export/pairs (google_data) — выгрузка утвержденных пар.
• Статус и конфигурацию синхронизации можно проверить через /api/sheets-status и /api/sheets-config (server).
• Файлы (CV, мотивации) доступны по GET /media/{id}; ссылки формируются при импорте.

Пайплайн матчинга

1. Импорт и изменения данных добавляют задачи в очередь (server/embedding_queue.py).
2. Сервис matching пересчитывает эмбеддинги (Sentence Transformers) и сохраняет векторы в Postgres (pgvector).
3. Запросы /api/match/* и /api/embeddings/* обрабатываются сервисом matching: выполняется поиск ближайших векторов, затем LLM ранжирует кандидатов.
4. Результаты попадают в очередь уведомлений; админы подтверждают или отклоняют пары через UI или Telegram.
5. Утвержденные решения при необходимости экспортируются обратно в Google Sheets.

Telegram-бот

• Реализован на Aiogram, запускается через bot/run_bot.py.
• Общается с сервером по HTTP (POST /notify, /api/messages/*, /api/bind-telegram).
• Список администраторов задается в server/admins.txt (поддерживаются Telegram ID, @username, https://t.me/...).
• Дополнительные таймауты/прокси настраиваются переменными TELEGRAM_CONNECT_TIMEOUT, TELEGRAM_PROXY_URL и т. п.

Структура репозитория

MentorMatch/
├─ admin/         # Административная панель (FastAPI + Jinja2 шаблоны)
├─ bot/           # Telegram-бот (Aiogram)
├─ google_data/   # Интеграция с Google Sheets и воркфлоу импорта
├─ matching/      # Эмбеддинги, LLM, матчинговый движок
├─ server/        # Основной REST API, медиахранилище, очереди
├─ docs/          # Дополнительная документация по контейнерам
├─ schema.sql     # Схема PostgreSQL (pgvector)
├─ schema.md      # Описание таблиц
├─ docker-compose.yml
└─ env.example

Локальная разработка

• Поднимите Postgres (например, docker compose up postgres).
• Установите зависимости и запустите нужный сервис:

  pip install -r server/requirements.txt
  uvicorn server.main:app --reload --port 8000
  

  Для остальных сервисов: matching/requirements.txt, admin/requirements.txt, bot/requirements.txt.
• Экспортируйте переменные окружения или используйте .env.
• Примените schema.sql для инициализации базы.

Частые операции

• Остановить сервисы: docker compose down
• Пересоздать БД (с удалением данных): docker compose down -v
• Смотреть логи: docker compose logs -f server (или другой сервис)
• Пересобрать контейнер после правок зависимостей: docker compose build <service>

Подробные заметки по каждому контейнеру находятся в docs/containers/*.md.