SVO Semantic Chunker

Описание

Алгоритм смыслового чанкования текста на основе SVO-троек и векторного распределения. Поддержка русского, английского и украинского языков. Выход — JSONL или SQLite с оценкой уверенности чанков.

Description

Semantic text chunking algorithm based on SVO triplets and vector proximity. Supports Russian, English, and Ukrainian. Output: JSONL or SQLite with chunk confidence scoring.

• Границы чанков оптимизируются по максимизации семантического отклонения между блоком и его S–V-ядром (vector proximity, maximization).

Внешние зависимости / External dependencies

• chunk-metadata-adapter

  • PyPi: pip install chunk-metadata-adapter
  • Служит "клеем" между разными микросервисами, проверяет отдаваемые метаданные на валидность, обеспечивает единый формат передачи chunk-метаданных между сервисами.
  • Используется для валидации и стандартизации метаданных чанков, интеграции с другими сервисами экосистемы.

• mcp-proxy-adapter

  • PyPi: pip install mcp-proxy-adapter
  • Автоматизирует создание API и REST-интерфейсов, предоставляет сервер для MCP-Proxy.
  • Позволяет быстро развернуть REST/JSON-RPC сервер для взаимодействия с MCP-Proxy и другими сервисами.

Поддерживаемые языки / Supported languages

• Русский (ru)
• Английский (en)
• Украинский (uk)
• Смешанные тексты (автоматическое разбиение на языковые блоки)

Быстрый старт / Quickstart

pip install svo-chunker
python -m spacy download en_core_web_sm

Python API

from svo_chunker.svo_chunker import SVOChunker
# CPU (по умолчанию)
chunker = SVOChunker()
# Явно включить GPU (если доступен)
chunker_gpu = SVOChunker(use_gpu=True)

# Пример для смешанного текста (русский, английский, украинский)
text = "Вона відкрила вікно. She went to the kitchen. Она испугалась."
chunk_pairs = await chunker.chunk_by_sv_semantics(text)
for chunk, chunk_vector in chunk_pairs:
    print(f"Chunk: {chunk}\nVector: {chunk_vector[:5]}...\n")

Формат вывода / Output format

chunk_by_sv_semantics возвращает список кортежей (chunk_dict, chunk_vector), где:

• chunk_dict — словарь с полями:
  • start, end — индексы токенов
  • sv — словарь с S–V парой (subject, verb)
  • block — список токенов
  • score — float, метрика качества
• chunk_vector — list[float], эмбеддинг чанка

Fallback-эвристика по алфавиту

Если язык не определён автоматически, используется эвристика:

• Если есть уникальные украинские буквы (ї, є, ґ) — uk
• Если кириллица без уникальных украинских — ru
• Если латиница — en
• Иначе блок пропускается

CLI

python -m svo_chunker.utils.chunk_text_cli.py -i input.txt -o output.jsonl --host http://localhost --port 8001 --show-vectors

• По умолчанию используется CPU. Для GPU используйте SVOChunker(use_gpu=True) в своем скрипте.

Best practices

• Для больших и смешанных текстов используйте пакетную обработку и GPU.
• Для грязных данных — алгоритм устойчив к ошибкам и автоматически разбивает на языковые блоки.
• Для тестирования используйте датасеты из папки datasets/.

Примеры / Examples

См. папку svo_chunker/examples/ (есть примеры для всех языков и смешанных текстов)

TODO

• SVO extraction
• Chunk boundary detection
• Residual allocation
• Confidence scoring
• Output formatting (JSONL/SQLite)

Установка моделей Stanza

Перед первым запуском необходимо вручную скачать модели Stanza для всех поддерживаемых языков:

python -c "import stanza; [stanza.download(lang) for lang in ['ru', 'en', 'uk']]"

Это действие требуется выполнить только один раз (или при обновлении моделей). После этого пакет будет использовать локальные копии моделей без повторных скачиваний.

⚠️ Загрузка моделей Stanza (RU/EN/UK)

Перед первым использованием необходимо скачать модели Stanza для русского, английского и украинского языков:

python -c "import stanza; stanza.download('ru'); stanza.download('en'); stanza.download('uk')"

Если вы запускаете тесты или используете пакет впервые, этот шаг обязателен. Иначе код попытается скачать модели автоматически при первом запуске (может "зависнуть" без интернета).

⚠️ Download Stanza models (RU/EN/UK)

Before first use, you must download Stanza models for Russian, English, and Ukrainian:

python -c "import stanza; stanza.download('ru'); stanza.download('en'); stanza.download('uk')"

If you run tests or use the package for the first time, this step is required. Otherwise, the code will try to download models automatically on first run (may hang if no internet).

Использование в Docker/контейнерах

1. Скачивание моделей при сборке контейнера

В Dockerfile:

FROM python:3.12
WORKDIR /app
COPY . /app
RUN pip install -r requirements.txt
# Скачиваем модели Stanza в /models/stanza_resources
RUN python -c "import stanza; stanza.download('ru', dir='/models/stanza_resources'); stanza.download('en', dir='/models/stanza_resources'); stanza.download('uk', dir='/models/stanza_resources')"
ENV STANZA_RESOURCES_DIR=/models/stanza_resources
CMD ["python", "your_script.py"]

2. Монтирование volume с моделями

На хосте:

python -c "import stanza; stanza.download('ru'); stanza.download('en'); stanza.download('uk')"

Запуск контейнера:

docker run -v ~/stanza_resources:/root/stanza_resources ...

3. Явное указание пути к моделям в коде

import stanza
stanza.download('ru', dir='/models/stanza_resources')
nlp = stanza.Pipeline(lang='ru', dir='/models/stanza_resources')

4. Рекомендации для production/CI/CD

• Всегда используйте переменную окружения STANZA_RESOURCES_DIR или параметр dir.
• Не храните большие модели внутри кода — используйте volume или отдельный слой Docker.
• Документируйте путь к моделям для всех участников команды.

Flat-модели метаданных чанков / Flat chunk metadata models

Что такое flat-модель?

Flat-модель — это упрощённое (плоское) представление метаданных чанка, где все поля вынесены на верхний уровень структуры (без вложенных объектов). Такой формат удобен для хранения в реляционных БД, передачи через API и интеграции с внешними сервисами.

Основные flat-модели:

• FlatSemanticChunk (из chunk-metadata-adapter):
  • Используется для хранения и передачи метаданных в формате, совместимом с большинством хранилищ и API.
  • Все поля — строки или простые типы (tags — строка, type — строка).
  • Поддерживает строгую валидацию (UUID, ISO8601, enum-значения).
  • Преобразование из/в полную модель: .from_semantic_chunk(), .to_semantic_chunk().
• ApiSemanticChunk (локальная модель для API):
  • Используется для формирования ответов сервера.
  • Современный контракт: tags — всегда список строк, type — строка (значение Enum), остальные поля совместимы с SemanticChunk.
  • Гарантирует строгую валидацию и прозрачность структуры для клиента.

Когда использовать flat-модель?

• Для интеграции с внешними сервисами, где требуется простой и предсказуемый формат (например, REST API, JSONL, SQLite).
• Для хранения в БД, где вложенные структуры неудобны.
• Для передачи между микросервисами, использующими разные языки/стек.

Когда использовать полную модель (SemanticChunk)?

• Для внутренней логики, сложной обработки, ML/аналитики, когда важна типизация и вложенность.
• Для валидации и преобразования данных перед сохранением или отправкой наружу.

Пример: FlatSemanticChunk (адаптер)

from chunk_metadata_adapter.models import FlatSemanticChunk
chunk = FlatSemanticChunk(
    uuid="...",
    type="Draft",
    text="...",
    tags="tag1,tag2",
    ...
)

Пример: ApiSemanticChunk (API)

from commands.api_models import ApiSemanticChunk
chunk = ApiSemanticChunk(
    uuid="...",
    type="Draft",
    text="...",
    tags=["tag1", "tag2"],
    ...
)

Варианты использования

• Сервер: всегда возвращает список объектов ApiSemanticChunk (контракт: tags — список, type — строка).
• Внешние клиенты: могут использовать FlatSemanticChunk для хранения или преобразования данных.
• Миграция и интеграция: flat-модели позволяют легко мигрировать данные между сервисами и версиями API.

Важно

• Всегда валидируйте данные перед отправкой клиенту через ApiSemanticChunk.
• Для совместимости с legacy-сервисами используйте FlatSemanticChunk и преобразование tags <-> строка.