Upload README.md

README.md

@@ -0,0 +1,429 @@
+---
+title: AI Scraper ФИПИ
+emoji: 🕷️
+colorFrom: blue
+colorTo: purple
+sdk: docker
+sdk_version: "docker"
+python_version: "3.11"
+app_file: app.py
+pinned: false
+---
+
+# 🕷️ AI Scraper ФИПИ
+
+Сервис для автоматического сбора заданий с сайта ФИПИ (fipi.ru) с использованием AI-анализа на основе **ruBERT**.
+
+---
+
+## ✨ Возможности
+
+- 🕷️ **Автоматический парсинг** заданий с сайта ФИПИ
+- 🧠 **AI-классификация** заданий через ruBERT
+- 💾 **Сохранение в Supabase** с автоматическим обновлением
+- 🚀 **Деплой на Hugging Face Spaces**
+- 📊 **REST API** для доступа к заданиям
+- 🔍 **Поиск** по заданиям
+- 📈 **Статистика** и аналитика
+
+---
+
+## 📁 Структура
+
+```
+ai-scraper/
+├── app.py                 # Основное FastAPI приложение
+├── scraper.py             # Парсер сайта ФИПИ
+├── rubert_client.py       # Клиент для ruBERT API
+├── supabase_client.py     # Интеграция с Supabase
+├── models.py              # Pydantic модели
+├── requirements.txt       # Python зависимости
+├── schema.sql             # SQL схема для Supabase
+├── Dockerfile             # Docker конфигурация
+├── hf_spaces_config.yaml  # Конфиг для Hugging Face
+├── .env.example           # Шаблон переменных окружения
+└── README.md              # Документация
+```
+
+---
+
+## 🚀 Быстрый старт
+
+### 1. Локальная разработка
+
+```bash
+cd ai-scraper
+
+# Создайте виртуальное окружение
+python -m venv venv
+
+# Активируйте
+venv\Scripts\activate  # Windows
+source venv/bin/activate  # Linux/Mac
+
+# Установите зависимости
+pip install -r requirements.txt
+
+# Скопируйте .env.example в .env (опционально)
+cp .env.example .env
+
+# Заполните .env своими ключами
+# ИЛИ настройте переменные окружения в вашей системе
+
+# Запустите сервер
+uvicorn app:app --reload --host 0.0.0.0 --port 8000
+```
+
+Откройте http://localhost:8000/docs для Swagger UI.
+
+---
+
+## ⚙️ Переменные окружения
+
+### Для локальной разработки
+
+Скопируйте `.env.example` в `.env` и заполните своими значениями:
+
+```env
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_SERVICE_KEY=your-service-role-key
+RUBERT_URL=https://your-rubert.hf.space
+FIPI_BASE_URL=https://fipi.ru
+```
+
+### Для Hugging Face Spaces
+
+**Не нужно загружать `.env` файл!** Настройте переменные через интерфейс:
+
+1. Откройте ваш Space
+2. Перейдите в **Settings** → **Secrets**
+3. Добавьте переменные:
+   - `SUPABASE_URL`
+   - `SUPABASE_SERVICE_KEY`
+   - `RUBERT_URL` (опционально)
+   - `FIPI_BASE_URL` (опционально)
+
+---
+
+## 🗄️ Настройка Supabase
+
+### 1. Создайте проект
+
+Перейдите на [Supabase](https://supabase.com) и создайте новый проект.
+
+### 2. Выполните SQL скрипт
+
+1. Откройте [SQL Editor](https://supabase.com/dashboard/project/_/sql/new)
+2. Скопируйте содержимое `schema.sql`
+3. Нажмите **Run**
+
+### 3. Получите ключи
+
+1. Перейдите в **Settings** → **API**
+2. Скопируйте:
+   - **Project URL** → `SUPABASE_URL`
+   - **service_role key** → `SUPABASE_SERVICE_KEY`
+
+---
+
+## 🧠 Настройка ruBERT
+
+### Вариант 1: Использование существующего API
+
+Если у вас уже есть развернутый ruBERT (как в основном проекте):
+
+```env
+RUBERT_URL=https://your-rubert-instance.hf.space
+```
+
+### Вариант 2: Развертывание ruBERT
+
+Создайте новый Space на Hugging Face с моделью ruBERT:
+
+1. [RuBERT от DeepPavlov](https://huggingface.co/deepvk/rubert-base-cased)
+2. Используйте шаблон Gradio или FastAPI
+3. Добавьте эндпоинты `/api/analyze` и `/api/embedding`
+
+---
+
+## 🌐 Деплой на Hugging Face Spaces
+
+### Шаг 1: Создайте Space
+
+1. Перейдите на [Hugging Face Spaces](https://huggingface.co/spaces)
+2. Нажмите **Create new Space**
+3. Заполните:
+   - **Space name**: `fipi-ai-scraper`
+   - **License**: MIT
+   - **SDK**: Docker
+   - **Visibility**: Public или Private
+
+### Шаг 2: Загрузите файлы
+
+```bash
+# Инициализируйте git в папке ai-scraper
+cd ai-scraper
+git init
+git add .
+git commit -m "Initial commit"
+
+# Добавьте remote вашего Space
+git remote add origin https://huggingface.co/spaces/YOUR_USERNAME/fipi-ai-scraper
+
+# Push в Space
+git push -u origin main
+```
+
+### Шаг 3: Настройте переменные окружения
+
+**Важно:** Не загружайте `.env` файл в репозиторий!
+
+В Settings вашего Space добавьте в **Secrets**:
+
+| Variable | Value |
+|----------|-------|
+| `SUPABASE_URL` | https://your-project.supabase.co |
+| `SUPABASE_SERVICE_KEY` | ваш service key |
+| `RUBERT_URL` | https://your-rubert.hf.space |
+| `FIPI_BASE_URL` | https://fipi.ru |
+
+⚠️ **Примечание:** Переменные окружения добавляются через интерфейс Hugging Face:
+**Settings** → **Repository secrets** → **New secret**
+
+### Шаг 4: Дождитесь деплоя
+
+Space автоматически соберет Docker образ и запустит приложение.
+
+---
+
+## 📡 API Endpoints
+
+| Метод | Эндпоинт | Описание |
+|-------|----------|----------|
+| GET | `/` | Информация об API |
+| GET | `/api/health` | Проверка статуса сервиса |
+| GET | `/api/tasks` | Получить все задания |
+| GET | `/api/tasks/latest` | Последние добавленные задания |
+| GET | `/api/tasks/{task_id}` | Получить задание по ID |
+| GET | `/api/tasks/type/{type}` | Задания по типу |
+| GET | `/api/tasks/search?q=` | Поиск заданий |
+| POST | `/api/scrape` | Запустить парсинг ФИПИ |
+| POST | `/api/analyze` | AI анализ существующих заданий |
+| GET | `/api/stats` | Статистика по заданиям |
+
+---
+
+## 📝 Примеры использования
+
+### Python
+
+```python
+import requests
+
+BASE_URL = "https://your-space.hf.space"
+
+# Получить последние задания
+response = requests.get(f"{BASE_URL}/api/tasks/latest?limit=10")
+tasks = response.json()
+print(f"Найдено заданий: {len(tasks)}")
+
+# Запустить парсинг ФИПИ
+response = requests.post(f"{BASE_URL}/api/scrape")
+result = response.json()
+print(result["message"])
+
+# Поиск заданий
+response = requests.get(f"{BASE_URL}/api/tasks/search?q=сочинение")
+tasks = response.json()
+
+# Получить статистику
+response = requests.get(f"{BASE_URL}/api/stats")
+stats = response.json()
+print(f"Всего заданий: {stats['total_tasks']}")
+```
+
+### cURL
+
+```bash
+# Health check
+curl https://your-space.hf.space/api/health
+
+# Получить задания
+curl https://your-space.hf.space/api/tasks/latest
+
+# Запустить скрапинг
+curl -X POST https://your-space.hf.space/api/scrape \
+  -H "Content-Type: application/json" \
+  -d '{"subject": "russian"}'
+
+# Поиск
+curl "https://your-space.hf.space/api/tasks/search?q=ЕГЭ"
+```
+
+---
+
+## 🔧 Конфигурация
+
+### Переменные окружения
+
+| Переменная | Описание | Пример |
+|------------|----------|--------|
+| `SUPABASE_URL` | URL проекта Supabase | `https://xxx.supabase.co` |
+| `SUPABASE_SERVICE_KEY` | Service role ключ Supabase | `eyJhbG...` |
+| `RUBERT_URL` | URL ruBERT API | `https://rubert.hf.space` |
+| `FIPI_BASE_URL` | Базовый URL ФИПИ | `https://fipi.ru` |
+| `PORT` | Порт приложения | `7860` |
+| `HOST` | Хост приложения | `0.0.0.0` |
+
+---
+
+## 🏗️ Архитектура
+
+```
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
+│   FIPIScraper   │────▶│  RuBERTClient    │────▶│  SupabaseClient │
+│   (BeautifulSoup)│    │  (HTTP API)      │     │  (Supabase JS)  │
+└─────────────────┘     └──────────────────┘     └─────────────────┘
+         │                       │                        │
+         ▼                       ▼                        ▼
+   fipi.ru                 ruBERT HF               Supabase DB
+   (парсинг)              (AI анализ)              (хранение)
+```
+
+### Поток данных
+
+1. **Скрапинг**: `FIPIScraper` парсит задания с fipi.ru
+2. **Анализ**: `RuBERTClient` анализирует текст задания
+3. **Сохранение**: `SupabaseClient` сохраняет в базу данных
+4. **API**: FastAPI предоставляет REST эндпоинты
+
+---
+
+## 🔒 Безопасность
+
+- ✅ **RLS (Row Level Security)** в Supabase
+- ✅ **Валидация данных** через Pydantic
+- ✅ **CORS** настроен для API
+- ✅ **Service Key** не экспонируется на клиенте
+
+---
+
+## 🛠️ Решение проблем
+
+### "Supabase не настроен"
+
+Проверьте переменные окружения:
+```bash
+echo $SUPABASE_URL
+echo $SUPABASE_SERVICE_KEY
+```
+
+### "RuBERT клиент не настроен"
+
+Убедитесь, что `RUBERT_URL` указан и API доступен:
+```bash
+curl https://your-rubert.hf.space/api/health
+```
+
+### Ошибки при скрапинге
+
+Сайт ФИПИ может блокировать запросы. Попробуйте:
+- Изменить `User-Agent` в `scraper.py`
+- Использовать прокси
+- Добавить задержки между запросами
+
+### Docker не собирается
+
+Проверьте логи:
+```bash
+docker build -t fipi-scraper .
+docker run -p 7860:7860 fipi-scraper
+```
+
+### Configuration error / Missing .env
+
+**Это нормально!** Для Hugging Face Spaces:
+1. Не загружайте `.env` в репозиторий
+2. Настройте переменные через **Settings** → **Repository secrets**
+3. Файл `.env.example` существует только для документации
+
+---
+
+## 📝 История изменений
+
+### Март 2026 - Исправление парсера ФИПИ
+
+**Исправленные проблемы:**
+- ❌ Неверные URL-адреса (404 ошибки)
+- ❌ SSL ошибки для поддоменов
+- ❌ Некорректный парсинг заголовков
+
+**Результат:**
+- ✅ Найдено заданий: 0 → 12
+- ✅ Все запросы возвращают 200 OK
+
+Подробности в [FIXES.md](FIXES.md)
+
+---
+
+## 📊 Мониторинг
+
+### Логи приложения
+
+```bash
+# Логи в Hugging Face Space
+# Settings → Logs
+
+# Локально
+uvicorn app:app --log-level debug
+```
+
+### Метрики
+
+- `/api/health` — статус сервисов
+- `/api/stats` — статистика заданий
+
+---
+
+## 🤝 Интеграция с основным проектом
+
+Этот сервис дополняет основной проект `refined-main`:
+
+1. **Импорт заданий** из ФИПИ в базу
+2. **AI-анализ** через тот же ruBERT
+3. **Единая Supabase** для обоих сервисов
+
+### Подключение
+
+В основном проекте добавьте:
+
+```typescript
+// services/fipiTasks.ts
+const FIPI_SCRAPER_URL = 'https://fipi-ai-scraper.hf.space';
+
+export async function fetchLatestTasks(limit = 10) {
+  const response = await fetch(`${FIPI_SCRAPER_URL}/api/tasks/latest?limit=${limit}`);
+  return response.json();
+}
+```
+
+---
+
+## 📚 Дополнительные ресурсы
+
+- [Документация FastAPI](https://fastapi.tiangolo.com/)
+- [Документация Supabase](https://supabase.com/docs)
+- [Hugging Face Spaces](https://huggingface.co/docs/hub/spaces)
+- [ruBERT модель](https://huggingface.co/deepvk/rubert-base-cased)
+- [ФИПИ](https://fipi.ru/)
+
+---
+
+## 📄 Лицензия
+
+MIT License
+
+---
+
+**Последнее обновление:** Март 2026  
+**Статус:** ✅ Готово к деплою