Skip to content

README.md

Latest commit

 

History

History
184 lines (150 loc) · 13.8 KB

README.md

File metadata and controls

184 lines (150 loc) · 13.8 KB
Raw

ПростоПонятно.ai 💡

License: MIT Python Version Framework

Веб-приложение для объяснения сложных тем, концепций, терминов или даже мемов простыми словами с помощью AI (Google Gemini). Реализовано полностью на FastAPI, включая обслуживание фронтенда и API.

Это приложение создано как демонстрация и Open Source проект. Вы можете использовать его как основу для своих идей!

Скриншот ПростоПонятно.ai

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

  • 🧠 Объяснение тем с помощью Google Gemini: Введите любой вопрос или тему и получите ответ.
  • 🎯 Разные уровни объяснения: Выберите, как объяснить - "просто", "как подростку", "как 5-летнему", "кратко (TL;DR)", "через плюсы и минусы" или попросите AI придумать метафору.
  • 🍕 Пользовательские аналогии: Предложите свою аналогию (например, "объясни на примере пиццы").
  • 📝 Markdown и подсветка кода: Ответы форматируются с помощью Markdown, а блоки кода подсвечиваются с помощью highlight.js.
  • ✂️ Копирование кода: Удобная кнопка для копирования содержимого блоков кода.
  • 💾 Сохранение ответов: Успешно сгенерированные и валидные ответы сохраняются в JSON-файлы для быстрого доступа и SEO.
  • 🔍 Асинхронный поиск: Быстрый поиск по заголовкам и началу текста сохраненных объяснений.
  • ⚙️ SEO-основы: Генерация отдельных страниц для каждого сохраненного объяснения, sitemap.xml и robots.txt.
  • 🚀 Полностью на FastAPI: Бэкенд, API и рендеринг HTML-страниц с помощью Jinja2 - всё в одном фреймворке.
  • 🎨 Обновленный UI: Чистый, адаптивный интерфейс с поиском в шапке.

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

  • Веб-фреймворк: FastAPI
  • Шаблонизатор: Jinja2
  • AI Модель: Google Gemini API (google-genai)
  • Markdown Рендеринг (Клиент): markdown-it
  • Подсветка Кода (Клиент): highlight.js
  • Асинхронность: asyncio, aiofiles
  • Хранение данных: Файловая система (JSON-файлы)
  • Запуск: Uvicorn

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

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

    git clone https://github.com/lrdcxdes/prosto-ponyatno-ai.git
cd prosto-ponyatno-ai

  2. Убедитесь, что у вас установлен Python 3.8+.

  3. Создайте и активируйте виртуальное окружение (рекомендуется):

    python -m venv venv
# Linux/macOS
source venv/bin/activate
# Windows
# venv\Scripts\activate

  4. Установите зависимости:

    pip install -r requirements.txt

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

    • Переименуйте файл .env.example в .env.
    • Откройте файл .env и вставьте ваш API-ключ от Google AI Studio (Gemini API): 
      GOOGLE_API_KEY="ВАШ_GOOGLE_GENERATIVE_AI_API_KEY"
      Вы можете получить ключ здесь: Google AI Studio

  6. Запустите приложение:

    uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
    • --reload: Автоматический перезапуск сервера при изменении кода (удобно для разработки).

  7. Откройте браузер и перейдите по адресу http://localhost:8000.

⚙️ Конфигурация

Основная конфигурация выполняется через файл .env:

  • GOOGLE_API_KEY: Обязательный API-ключ для доступа к Google Gemini API.

Приложение автоматически создает папку app/explanations для хранения JSON-файлов с объяснениями.

▶️ Использование

  1. Главная страница (/):
    • Введите тему или вопрос в текстовое поле.
    • Выберите желаемый стиль объяснения из выпадающего списка.
    • Если выбран стиль "С моей аналогией...", введите вашу аналогию в появившееся поле.
    • Нажмите кнопку "Объяснить!".
    • Результат появится ниже с форматированием Markdown и подсветкой кода. Если объяснение было успешно сохранено, появится ссылка на его постоянную страницу.
  2. Поиск (в шапке):
    • Начните вводить запрос (минимум 3 символа) в поле поиска.
    • Появится выпадающий список с найденными сохраненными объяснениями.
    • Кликните на результат, чтобы перейти на страницу этого объяснения.
  3. Страница объяснения (/explanation/{slug}):
    • Отображает конкретное сохраненное объяснение.
    • Имеет уникальный URL, который можно добавить в закладки или поделиться.

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

prosto-ponyatno-ai/
├── app/
│ ├── main.py # Основной файл FastAPI (эндпоинты UI и API)
│ ├── services.py # Бизнес-логика (AI, файлы, поиск)
│ ├── models.py # Pydantic модели (запросы, ответы, хранение)
│ ├── core/
│ │ └── config.py # Загрузка конфигурации (.env)
│ ├── static/ # Статические файлы (CSS, JS)
│ │ ├── styles.css
│ │ └── script.js
│ ├── templates/ # Jinja2 HTML шаблоны
│ │ ├── index.html
│ │ └── explanation_page.html
│ └── explanations/ # Директория для хранения JSON файлов с объяснениями (создается автоматически)
│ └── .gitkeep
├── requirements.txt # Зависимости Python
├── .env.example # Пример файла переменных окружения
├── .gitignore
└── README.md # Этот файл

💡 Принцип работы

  1. Запрос пользователя (UI): Пользователь заполняет форму на главной странице (index.html). JavaScript (script.js) отправляет POST-запрос на /api/explain с темой и параметрами.
  2. Обработка API (FastAPI): Эндпоинт /api/explain в main.py принимает запрос.
  3. Сервисный слой (services.py):
    • Функция get_or_create_explanation генерирует slug для запроса.
    • Проверяет, существует ли файл app/explanations/{slug}.json (кеш).
    • Если файл есть, читает и возвращает его содержимое.
    • Если файла нет:
      • Формирует промпт для Google Gemini API на основе темы и выбранного уровня/аналогии.
      • Отправляет запрос к generate_ai_explanation.
      • Получает ответ от AI.
      • Валидирует ответ: Проверяет на наличие ошибок, индикаторов неудачи, минимальную длину.
      • Если ответ валиден: Генерирует метаданные (title, description), создает объект StoredExplanation и асинхронно сохраняет его в JSON-файл (save_explanation_to_file).
      • Возвращает текст объяснения и slug.
      • Если ответ не валиден: Возвращает текст (ошибки или невалидный ответ) и None вместо slug.
  4. Ответ API: Эндпоинт /api/explain возвращает JSON с текстом объяснения и slug (или null, если сохранение не произошло).
  5. Отображение (UI): JavaScript на главной странице получает ответ:
    • Если slug есть, рендерит Markdown-текст с помощью markdown-it и highlight.js, добавляет кнопки копирования и показывает ссылку на /explanation/{slug}.
    • Если slug равен null, показывает сообщение об ошибке или невалидный ответ.
  6. Страница объяснения (/explanation/{slug}):
    • GET-запрос обрабатывается в main.py.
    • load_explanation_from_file читает нужный JSON-файл.
    • Данные передаются в шаблон explanation_page.html.
    • JavaScript в шаблоне рендерит Markdown из переданного текста при загрузке страницы.
  7. Поиск:
    • JavaScript отправляет GET-запросы на /api/search?q=... по мере ввода в search-input.
    • Эндпоинт /api/search вызывает search_explanations, которая асинхронно ищет совпадения q в именах файлов (topic_raw) и содержимом (explanation_text) JSON-файлов.
    • Возвращается список найденных slug и topic.
    • JavaScript отображает результаты в виде ссылок.

🤝 Участие в разработке (Contributing)

Буду рад вашему участию! Если у вас есть идеи по улучшению, предложения или вы нашли баг:

  1. Issues: Пожалуйста, создайте Issue для обсуждения вашей идеи или проблемы.
  2. Pull Requests:
    • Сделайте форк репозитория.
    • Создайте новую ветку для вашей фичи (git checkout -b feature/AmazingFeature).
    • Сделайте ваши изменения.
    • Закоммитьте изменения (git commit -m 'Add some AmazingFeature').
    • Отправьте ветку в ваш форк (git push origin feature/AmazingFeature).
    • Создайте Pull Request.

📄 Лицензия

Этот проект распространяется под лицензией MIT. Смотрите файл LICENSE для подробностей (Вам нужно будет добавить файл LICENSE с текстом MIT лицензии в репозиторий).

🔮 Возможные будущие улучшения

  • Переход на базу данных: Использовать БД (например, PostgreSQL с pg_trgm или SQLite для простоты) вместо JSON-файлов для более эффективного хранения и поиска.
  • Кеширование: Внедрить кеширование (например, с помощью Redis) для API-ответов.
  • Оценка ответов: Добавить кнопки 👍/👎 для сбора обратной связи от пользователей.
  • Улучшенный поиск: Полнотекстовый поиск, учет релевантности, исправление опечаток.
  • Админ-панель: Простой интерфейс для управления сохраненными объяснениями.
  • Тесты: Написание Unit и Integration тестов.
  • Docker-контейнеризация: Упаковка приложения в Docker для легкого развертывания.

Надеюсь, этот проект будет полезен! Удачи!