ruwiki-test/README.md

# RuWiki -> SchoolNotes

Асинхронная система упрощения статей RuWiki для школьного образования с использованием LLM OpenAI.

[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
![Coverage](https://img.shields.io/badge/coverage-68%25-yellow)

## Описание

Система автоматически:
- Загружает статьи из русской Википедии
- Упрощает содержимое для учеников 8-11 классов с помощью OpenAI GPT
- Сохраняет оригинальный и упрощённый текст в SQLite
- Обрабатывает статьи параллельно

## Архитектура

```mermaid
graph TD
    A[CLI / AsyncRunner] -->|URLs| B[TaskQueue asyncio_anyio]
    B --> C[Worker_N coroutine]
    C --> D[RuWikiAdapter]
    C --> E[TextSplitter]
    C --> F[LLMProvider]
    C --> G[WriteQueue]
    G --> H[(SQLite 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       # Зависимости
```