Metadata-Version: 2.4
Name: svo-client
Version: 4.0.10
Summary: Client for the SVO semantic chunking service
Home-page: https://github.com/maverikod/vvz-svo-chunker
Author: Vasiliy Zdanovskiy
Author-email: vasilyvz@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: aiohttp
Requires-Dist: chunk-metadata-adapter>=3.4.0
Requires-Dist: mcp-proxy-adapter>=8.10.69
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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

```bash
pip install svo-chunker
python -m spacy download en_core_web_sm
```

### Python API
```python
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
```bash
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 для всех поддерживаемых языков:

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

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

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

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

```bash
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:

```bash
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:
```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 с моделями

На хосте:
```bash
python -c "import stanza; stanza.download('ru'); stanza.download('en'); stanza.download('uk')"
```
Запуск контейнера:
```bash
docker run -v ~/stanza_resources:/root/stanza_resources ...
```

### 3. Явное указание пути к моделям в коде
```python
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 (адаптер)
```python
from chunk_metadata_adapter.models import FlatSemanticChunk
chunk = FlatSemanticChunk(
    uuid="...",
    type="Draft",
    text="...",
    tags="tag1,tag2",
    ...
)
```

### Пример: ApiSemanticChunk (API)
```python
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 <-> строка. 
