vector/scripts/README.md

# Скрипт парсинга спецдонесений МЧС

## Описание

`parse_reports.py` - скрипт для автоматического извлечения структурированных данных из спецдонесений МЧС Беларуси в формате .docx с использованием Claude API.

## Возможности

- ✅ Чтение .docx файлов через python-docx
- ✅ Извлечение 18 полей данных через Claude API
- ✅ Оценка уверенности (confidence) для каждого поля
- ✅ Автоматическая фильтрация по качеству данных
- ✅ Сохранение в PostgreSQL (таблицы cases + raw_documents)
- ✅ Режим dry-run для тестирования
- ✅ Детальное логирование и отчеты

## Извлекаемые поля

1. `age_years` - возраст в годах
2. `gender` - пол (мужской/женский)
3. `has_diagnosis` - наличие диагноза/заболевания
4. `diagnosis_type` - тип диагноза
5. `has_transport` - наличие транспорта
6. `season` - сезон (winter/spring/summer/autumn)
7. `time_of_day` - время суток (morning/day/evening/night)
8. `elapsed_before_report_h` - часов до сообщения
9. `last_seen_direction` - направление последнего наблюдения
10. `terrain_primary` - основной тип местности
11. `water_nearby` - водоем рядом
12. `road_nearby` - дорога рядом
13. `found_alive` - найден живым
14. `found_distance_km` - расстояние обнаружения (км)
15. `found_direction` - направление обнаружения
16. `found_location_type` - тип места обнаружения
17. `search_duration_hours` - длительность поиска (часы)
18. `who_found` - кто нашел

Каждое поле имеет:
- `value` - значение или null
- `confidence` - уровень уверенности (high/medium/low)

## Установка

### 1. Создание таблиц в БД

```bash
cd /root/sar-mchs/scripts

# Подключитесь к PostgreSQL и выполните:
psql -U postgres -d sar_mchs -f create_tables.sql
```

Или через Docker:
```bash
docker exec -i sar-mchs-postgres psql -U postgres -d sar_mchs < create_tables.sql
```

### 2. Установка зависимостей

Зависимости уже установлены в backend/requirements.txt:
- python-docx
- httpx
- sqlalchemy[asyncio]
- asyncpg

### 3. Настройка переменных окружения

```bash
export ANTHROPIC_API_KEY="your_api_key_here"
export DATABASE_URL="postgresql+asyncpg://postgres:postgres@localhost:5432/sar_mchs"
```

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

### Базовое использование

```bash
cd /root/sar-mchs/scripts

# Dry-run (без записи в БД)
python3 parse_reports.py --dir /path/to/docx/files --dry-run

# Запись в БД
python3 parse_reports.py \
  --dir /path/to/docx/files \
  --db "postgresql+asyncpg://postgres:postgres@localhost:5432/sar_mchs"
```

### Параметры

- `--dir` (обязательный) - путь к папке с .docx файлами
- `--db` (опциональный) - DATABASE_URL для PostgreSQL
- `--dry-run` (флаг) - режим тестирования без записи в БД

### Примеры

**1. Тестовый запуск:**
```bash
python3 parse_reports.py --dir ./test_reports --dry-run
```

**2. Обработка с записью в БД:**
```bash
export ANTHROPIC_API_KEY="sk-ant-..."
python3 parse_reports.py \
  --dir /data/mchs_reports \
  --db "postgresql+asyncpg://postgres:postgres@postgres:5432/sar_mchs"
```

**3. Обработка из Docker контейнера:**
```bash
docker exec -it sar-mchs-backend bash
cd /app/scripts
python3 parse_reports.py --dir /data/reports --db $DATABASE_URL
```

## Логика работы

1. **Чтение файлов**: Сканирует директорию на наличие .docx файлов
2. **Извлечение текста**: Использует python-docx для чтения содержимого
3. **Анализ через Claude**: Отправляет текст в Claude API с промптом извлечения
4. **Валидация**: Подсчитывает поля с high confidence
5. **Фильтрация**: Пропускает файлы с < 6 полей high confidence
6. **Сохранение**: Записывает в таблицы raw_documents и cases
7. **Отчет**: Генерирует parse_report.json с детальной статистикой

## Выходные данные

### Консольный вывод

```
2026-05-01 10:15:23 - INFO - Найдено файлов: 15
2026-05-01 10:15:23 - INFO - Режим: ЗАПИСЬ В БД
2026-05-01 10:15:24 - INFO - Обработка: report_001.docx
2026-05-01 10:15:28 - INFO -   Полей с high confidence: 12/18
2026-05-01 10:15:29 - INFO - ✓ Сохранено в БД: report_001.docx (doc_id=1)
...
2026-05-01 10:20:15 - INFO - ============================================================
2026-05-01 10:20:15 - INFO - ИТОГОВАЯ СТАТИСТИКА
2026-05-01 10:20:15 - INFO - ============================================================
2026-05-01 10:20:15 - INFO - Всего файлов: 15
2026-05-01 10:20:15 - INFO - Успешно обработано: 12
2026-05-01 10:20:15 - INFO - Пропущено (< 6 high conf): 2
2026-05-01 10:20:15 - INFO - Ошибки: 1
```

### Файл отчета (parse_report.json)

```json
[
  {
    "file": "report_001.docx",
    "status": "success",
    "high_confidence_count": 12
  },
  {
    "file": "report_002.docx",
    "status": "skipped",
    "reason": "Недостаточно полей с high confidence (4 < 6)",
    "high_confidence_count": 4
  }
]
```

## Структура БД

### Таблица raw_documents
- `id` - первичный ключ
- `filename` - имя файла
- `raw_text` - исходный текст
- `extracted_json` - JSON с извлеченными данными
- `created_at`, `updated_at` - временные метки

### Таблица cases
- `id` - первичный ключ
- `raw_document_id` - ссылка на raw_documents
- 18 полей данных (см. выше)
- `created_at`, `updated_at` - временные метки

## Ограничения и рекомендации

- **Rate limiting**: Скрипт делает паузу 1 секунду между запросами к Claude API
- **Длина текста**: Ограничена 8000 символами для промпта
- **Минимальный порог**: Файлы с < 6 полей high confidence пропускаются
- **Стоимость**: Каждый файл = 1 запрос к Claude API (~$0.003-0.015 за файл)

## Troubleshooting

**Ошибка: "ANTHROPIC_API_KEY не установлен"**
```bash
export ANTHROPIC_API_KEY="your_key_here"
```

**Ошибка подключения к БД**
```bash
# Проверьте DATABASE_URL
echo $DATABASE_URL

# Проверьте доступность PostgreSQL
docker exec sar-mchs-postgres pg_isready
```

**Файлы не найдены**
```bash
# Проверьте путь и наличие .docx файлов
ls -la /path/to/docx/files/*.docx
```

## TODO

- [ ] Добавить поддержку .pdf файлов
- [ ] Batch обработка для снижения стоимости API
- [ ] Retry логика при ошибках API
- [ ] Прогресс-бар для больших объемов
- [ ] Экспорт в CSV/Excel
- [ ] Web-интерфейс для мониторинга