NeuroTest

Бекенд для сервиса по прохождению тестов с использованием LLM.

Описание

NeuroTest — это веб-приложение для загрузки тестов в формате .docx, которые автоматически преобразуются в структурированный JSON с помощью LLM. Затем система находит правильные ответы на вопросы. Пользователь также может вручную добавлять, редактировать или удалять тесты, вопросы и ответы через Swagger UI (бэкенд-документацию).

Проект реализован на FastAPI (бэкенд) с интеграцией OpenRouter и Cerebras для работы с моделями, а также Tavily для поисковых запросов.

Технологии

Бэкенд: Python 3.11+, FastAPI, SQLAlchemy, Alembic, PostgreSQL, Pydantic
Интеграция с AI: LangChain, OpenRouter, Cerebras, Tavily
Инфраструктура: Docker, Uvicorn, JWT, Argon2
Работа с файлами: docx2txt, aiofiles

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

📁 NeuroTest/
├── 📁 backend/                    # FastAPI-бэкенд
│   ├── 📁 api/                    # REST-эндпоинты (auth, llm, тесты, вопросы, ответы)
│   ├── 📁 core/                   # Подключение к БД и глобальные настройки
│   ├── 📁 services/               # Бизнес-логика
│   ├── 📁 models/                 # SQLAlchemy модели
│   ├── 📁 repositories/           # операции с БД
│   ├── 📁 schemas/                # Pydantic-схемы для валидации
│   ├── 📁 infrastructure/         # Вспомогательные утилиты (файловое хранилище)
│   ├── 📁 alembic/                # Миграции базы данных
│   ├── 📁 files/                  # Загруженные файлы (игнорируется в git)
│   ├── 🐍 main.py                 # Точка входа FastAPI
│   ├── 🐳 Dockerfile              # Инструкция для сборки образа
│   └── 📄 pyproject.toml          # Зависимости проекта
├── 📁 frontend/
│   └── 🌐 index.html              # Простой интерфейс для тестов
├── 🐳 docker-compose.yml          # Оркестрация контейнеров
└── 📄 .env.example                # Шаблон переменных окружения

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

Этот способ поднимает всё приложение целиком: бэкенд, базу данных и удобный интерфейс для управления БД.

1. Клонируйте репозиторий:

   git clone https://github.com/TigranAko/NeuroTest.git
   cd NeuroTest/backend

2. Скопируйте файл с примером переменных окружения и заполните своими данными:

   cp .env.example .env

   Отредактируйте .env, указав свои API-ключи и настройки JWT

3. Запуск всех сервисов

Из корневой директории проекта выполните:

docker compose up --build -d

Примечание: в новых версиях Docker используется команда docker compose (без дефиса). Если у вас старая версия, используйте docker-compose (с дефисом).

Флаг -d запускает контейнеры в фоновом режиме.
Флаг --build принудительно пересобирает образ перед запуском – полезно после внесения изменений в Dockerfile или в код приложения.

4. Что будет запущено

Сервис	Доступ по адресу	Назначение
FastAPI	http://localhost:8000	Бэкенд-приложение (API и Swagger UI)
Adminer	http://localhost:8080	Визуальный клиент для управления БД
PostgreSQL	localhost:5432 (внутри сети)	База данных (не имеет прямого веб-интерфейса)

5. Остановка контейнеров

docker compose down

Чтобы остановить контейнеры и удалить все данные базы данных (volumes):

docker compose down -v

API Документация

После запуска проекта интерактивная документация доступна по адресам:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Документация содержит все эндпоинты с примерами запросов и ответов.

Лицензия

MIT License. Подробнее см. в файле LICENSE.

Авторы

• TigranAko
• Maksimushkamolnia2001