components/parser/abbreviations/README.md

# Экстрактор сокращений (Abbreviation Extractor)

> ВАЖНО!!! README.md сгенерировано автоматически, поэтому может содержать неточности.

Модуль для извлечения сокращений и их полных форм из текстовых документов.

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

Экстрактор ищет в тексте конструкции вида:
- "полная форма (далее - сокращение)"
- "полная форма (далее – сокращение)"
и подобные варианты.

### Основные этапы обработки:

1. **Разбиение на предложения**
   - Текст разбивается на предложения с учетом специальных случаев
   - Учитываются особые сокращения, после которых точка не является концом предложения

2. **Поиск сокращений**
   - В каждом предложении ищутся конструкции с маркером "далее"
   - Извлекается короткая форма (сокращение) после маркера
   - Определяется полная форма до маркера

3. **Обработка сокращений**
   - Поддерживается два типа сокращений:
     - Однословные (например, "*БЖВРК*")
     - Многословные (например, "Мы великая нация великих обезьян (далее - *нация обезьян*)")
   - Для каждого сокращения определяется его полная форма

4. **Лемматизация**
   - Используется библиотека Natasha для лемматизации текста
   - Помогает находить соответствия между полной и короткой формами

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

```python
from components.parser.abbreviations.abbreviation_extractor import AbbreviationExtractor
from components.parser.xml.structures import ParsedXMLs

# Создание экстрактора
extractor = AbbreviationExtractor()

# Обработка XML-файлов
result = extractor.process_parsed_xmls(parsed_xmls)

# Обработка одного файла
file_abbreviations = extractor.process_file(text, filename)

# Извлечение сокращений из текста
abbreviations = extractor.extract_abbreviations_from_text(text)
```

## Структура результатов

Результаты представляются в виде структур данных:
- `AllFilesAbbreviations` - коллекция сокращений из всех файлов
- `OneFileAbbreviations` - сокращения из одного файла
- `Abbreviation` - отдельное сокращение с полной и короткой формами

## Особенности

- Учитываются различные варианты разделителей между полной и короткой формами
- Поддерживается обработка специальных сокращений, не являющихся концом предложения
- Используется лемматизация для улучшения поиска соответствий
- Возможна обработка как одиночных файлов, так и наборов файлов

# Обработка сокращений и аббревиатур

Модуль `abbreviation.py` отвечает за обработку и нормализацию сокращений и аббревиатур в тексте.

## Основные типы сокращений

- `ABBREVIATION` - аббревиатуры (например, "ОКС НН")
- `SHORTENING` - сокращения (например, "Компания")
- `UNKNOWN` - неопределенный тип

## Процесс обработки

Класс `Abbreviation` выполняет следующие этапы обработки:

1. **Определение типа сокращения** (`_define_abbreviation_type`):
   - Проверяет, является ли строка аббревиатурой (содержит более одной заглавной буквы в каждом слове)
   - Проверяет, является ли строка сокращением (одно слово, начинающееся с заглавной буквы)

2. **Очистка префиксов** (`_remove_prefix`):
   - Удаляет такие префиксы как "далее", различные виды тире
   - Убирает лишние пробелы

3. **Очистка от мусора** (`_remove_trash`):
   - Удаляет такие подстроки как "ПАО", "ОАО", "№", "("
   - Обрезает строку с начала до первого вхождения "мусорной" подстроки

4. **Специальная обработка для аббревиатур** (`_process_abbreviation`):
   - Извлекает заглавные буквы из короткой формы
   - Проверяет соответствие заглавных букв началам слов в полной форме
   - Обрезает полную форму до релевантной части

5. **Специальная обработка для сокращений** (`_process_shortening`):
   - Применяет стемминг (с помощью алгоритма Портера) к короткой форме
   - Обрезает полную форму до релевантной части

## Валидация

- Проверяет длину полной формы (должна быть меньше MAX_LENGTH)
- Проверяет, что полная форма длиннее короткой
- Проверяет отсутствие полной формы в черном списке (BLACKLIST)
- Для аббревиатур проверяет соответствие заглавных букв началам слов
- Для сокращений проверяет корректность регистра букв и отсутствие специальных случаев

Если какая-либо проверка не проходит, тип сокращения устанавливается как `UNKNOWN`.


# Применение сокращений и аббревиатур

Класс `Abbreviation` имеет метод `apply`, который принимает текст и возвращает текст с примененными сокращениями и аббревиатурами.

Класс