Add readme

2025-07-12 11:53:01 +03:00 · 2025-07-12 11:53:01 +03:00 · debb371c69
parent fef5023d74
commit debb371c69
1 changed files with 239 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,239 @@
+# RuWiki -> SchoolNotes
+
+Асинхронная система упрощения статей RuWiki для школьного образования с использованием LLM OpenAI.
+
+## Описание
+
+Система автоматически:
+- Загружает статьи из русской Википедии
+- Упрощает содержимое для учеников 8-11 классов с помощью OpenAI GPT
+- Сохраняет оригинальный и упрощённый текст в SQLite
+- Обрабатывает статьи параллельно
+
+## Архитектура
+
+```mermaid
+graph TD
+    A[CLI / AsyncRunner] -->|URLs| B[TaskQueue<br>(asyncio + anyio)]
+    B --> C[Worker N<br>(coroutine)]
+    C --> D[RuWikiAdapter]
+    C --> E[TextSplitter]
+    C --> F[LLMProvider]
+    C --> G[WriteQueue]
+    G --> H[(SQLite<br>aiosqlite)]
+```
+
+## Установка
+
+### Требования
+- Python ≥ 3.10
+- OpenAI API ключ
+
+### Установка зависимостей
+
+```bash
+# Создание виртуального окружения
+python -m venv .venv
+source .venv/bin/activate  # Linux/Mac
+# или
+.venv\Scripts\activate     # Windows
+
+# Установка зависимостей
+pip install -r requirements.txt
+
+# Для разработки
+pip install -r requirements-dev.txt
+```
+
+### Конфигурация
+
+1. Скопируйте `env_example.txt` в `.env`:
+```bash
+cp env_example.txt .env
+```
+
+2. Настройте конфигурацию в env:
+```env
+OPENAI_API_KEY=your_openai_api_key_here
+...
+```
+
+## Использование
+
+### Основные команды
+
+```bash
+# Обработка статей из файла
+python -m src.cli process input.txt
+
+# Принудительная обработка (повторная)
+python -m src.cli process input.txt --force
+
+# Ограничение количества статей
+python -m src.cli process input.txt --max-articles 10
+
+# Настройка количества workers
+python -m src.cli process input.txt --max-workers 5
+
+# Проверка здоровья системы
+python -m src.cli health
+
+# Просмотр статей в БД
+python -m src.cli list-articles --limit 20
+
+# Статистика по файлу с URL
+python -m src.cli stats input.txt
+```
+
+### Формат файла с URL
+
+```
+# input.txt
+https://ru.ruwiki.ru/wiki/Изотопы
+https://ru.ruwiki.ru/wiki/Вещественное_число
+https://ru.ruwiki.ru/wiki/Митоз
+```
+
+### Примеры
+
+```bash
+# Обработка тестовых статей
+python -m src.cli process input.txt --max-articles 3 --max-workers 2
+
+# Вывод результатов в JSON
+python -m src.cli list-articles --format json --status completed
+
+# Настройка логирования
+python -m src.cli --log-level DEBUG --log-format json process input.txt
+```
+
+## Конфигурация
+
+Основные параметры в `.env`:
+
+```env
+# OpenAI
+OPENAI_API_KEY=your_openai_api_key_here
+OPENAI_MODEL=gpt-4o
+OPENAI_TEMPERATURE=0.0
+OPENAI_PROXY_URL='socks5h://37.18.73.60:5566'  # socks5 recommended
+
+# База данных
+DB_PATH=./data/wiki.db
+
+# Производительность
+MAX_CONCURRENT_LLM=5
+OPENAI_RPM=200
+MAX_CONCURRENT_WIKI=10
+
+# Логирование
+LOG_LEVEL=INFO
+LOG_FORMAT=json
+
+# Обработка текста
+CHUNK_SIZE=2000
+CHUNK_OVERLAP=200
+
+# Надёжность
+MAX_RETRIES=3
+RETRY_DELAY=1.0
+CIRCUIT_FAILURE_THRESHOLD=5
+CIRCUIT_RECOVERY_TIMEOUT=60
+```
+
+## 📊 Мониторинг
+
+### Логи
+```bash
+# Структурированные логи в JSON
+python -m src.cli --log-format json process input.txt
+
+# Отладочные логи
+python -m src.cli --log-level DEBUG process input.txt
+```
+
+### Метрики
+- Скорость обработки: статей/минуту
+- Процент успеха
+- Среднее время обработки
+- Использование токенов
+
+### Health Check
+```bash
+python -m src.cli health
+```
+
+## Тестирование
+
+```bash
+# Все тесты
+python -m pytest
+
+# С покрытием
+python -m pytest --cov=src --cov-report=html
+
+# Без покрытия (быстрее)
+python -m pytest --no-cov
+
+# Только unit тесты
+python -m pytest tests/test_models.py tests/test_adapters.py
+
+# Интеграционные тесты
+python -m pytest tests/test_integration.py
+
+# Конкретный тест
+python -m pytest tests/test_adapters.py::TestLLMProviderAdapter::test_simplify_text_success -v
+
+```
+
+### Статус тестов
+- ✅ **71 тест** - все проходят
+- ✅ **Unit тесты** - адаптеры, модели, сервисы
+- ✅ **Интеграционные тесты** - база данных, файловые операции
+- ✅ **Системные тесты** - полный цикл обработки
+
+## Примеры результатов
+
+### Исходная статья (фрагмент)
+```wiki
+'''Изотопы''' (от {{lang-grc|ἴσος}} «равный» и {{lang-grc|τόπος}} «место») — разновидности атомов химического элемента с одинаковым количеством протонов, но различным количеством нейтронов в ядре...
+```
+
+### Упрощённая версия
+```wiki
+'''Изотопы''' — это разные виды атомов одного элемента.
+
+== Что такое изотопы ==
+У атомов одного элемента всегда одинаковое число протонов. Но число нейтронов может быть разным. Атомы с разным числом нейтронов называются изотопами...
+```
+
+## Разработка
+
+### Качество кода
+```bash
+# Форматирование
+black src/ tests/
+
+# Проверка стиля
+ruff check src/
+
+# Типы
+mypy src/
+
+# Безопасность
+bandit -r src/
+```
+
+### Структура проекта
+```
+ruwiki_test/
+├── src/
+│   ├── adapters/          # Адаптеры для внешних API
+│   ├── models/            # Модели данных
+│   ├── services/          # Бизнес-логика
+│   ├── cli.py            # CLI интерфейс
+│   └── runner.py         # Основной runner
+├── tests/                 # Тесты
+├── data/                  # База данных
+└── requirements.txt       # Зависимости
+```