svo-client-dev 4.0.21__tar.gz

svo_client_dev-4.0.21/PKG-INFO

@@ -0,0 +1,363 @@
+Metadata-Version: 2.4
+Name: svo-client-dev
+Version: 4.0.21
+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: jsonschema<5,>=4.18
+Requires-Dist: mcp-proxy-adapter>=8.11.9
+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
+
+The only release entrypoint is `./build.sh [dev=yes|no] [VERSION]`, run from
+the authoritative checkout on branch `local`; DEV is the default. For
+local-only client artifacts, use `env dontpubpypi=1 ./build.sh dev=yes VERSION`.
+Production promotion requires a direct owner order and the exact sealed full-DEV
+GREEN receipt; it performs no rebuild. See
+[DEV/PROD installation and promotion](docs/dev-prod.md).
+
+## Описание
+
+Алгоритм смыслового чанкования текста на основе 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.
+
+## Public service API
+
+Use `svo_client.SvoChunkerClient` for the running service. `chunk(text, ...)`
+returns chunks for one input; `chunk_batch(texts, ...)` returns one ordered chunk
+list per input. The JSON-RPC command is `chunk` and accepts `texts` (1..8 inputs),
+each at most 1 MiB (1,048,576 UTF-8 bytes). The wire result is NDJSON, inline or
+downloaded through an adapter transfer. The client handles both forms.
+
+```python
+from svo_client import SvoChunkerClient
+from svo_client.config import ClientConfig
+
+# Alternatively pass your configured host, port and TLS credentials directly.
+async with SvoChunkerClient(**ClientConfig().get_client_config()) as client:
+    source = "First paragraph.\n\nSecond paragraph with a long sentence."
+    chunks = await client.chunk(
+        source, split_level="paragraph", max_chars=32, use_sv=False,
+    )
+    assert "".join(chunk["body"] for chunk in chunks) == source
+    for chunk in chunks:
+        assert len(chunk["body"]) <= 32
+        assert source[chunk["global_start"]:chunk["global_end"]] == chunk["body"]
+```
+
+### Exact segmentation and semantic chunking
+
+`split_level="paragraph"|"sentence"|"word"` requests exact source segments.
+Supplying `split_level` or a positive integer `max_chars` selects an early path
+that skips code/formula/language processing, minimum-length merging, SV,
+embedding, recovery and vector reuse. `chunk_only` is implicit on this path;
+even explicit `chunk_only=False` does not request embeddings. `use_sv=True` is
+rejected. `max_chars` alone uses paragraph boundaries, with sentence, word and
+finally hard-split fallbacks. Its unit is Python characters, not tokens or UTF-8
+bytes. No `max_tokens` parameter is implemented.
+
+Without either segmentation option, ordinary chunking runs structural
+paragraph splitting, code and formula handling, pySBD sentence splitting,
+long-chunk splitting, language handling, short-chunk merging, optional paragraph
+aggregation/preset policy, optional SV, then vectorization. pySBD supports
+English, Russian and Ukrainian, with punctuation fallback. `type="Comment"`
+skips sentence splitting, short-chunk merging and effective SV. Legacy defaults
+are `min_chunk_length=15` and `max_chunk_length=2000` characters from server
+configuration; short inputs produce per-item errors. `window` accepts 1..10,
+default 3. Paragraph aggregation requires effective SV to be disabled and is
+capped by `max_chunk_length`.
+
+For ordinary chunking without final vectorization, use `chunk_only=True` and
+`use_sv=False`. Chunk-only processing skips natural-language detection and the
+entire language-analysis stage, whether `language` is supplied or omitted.
+The legacy path still requires configured
+`embedding_config.base_url` or `embedding_client.base_url`. `chunk_only=True`
+alone does not promise that `use_sv=True` avoids embedding work. The early
+segmentation path needs no embedding configuration.
+
+`body` preserves the original source exactly, including whitespace and CRLF;
+join it in source order to reconstruct an input. `text` is a separate normalized
+representation for search/vectorization. Existing `start`/`end` retain
+block-local compatibility; segmentation also supplies `global_start` and
+`global_end` as character offsets into each original input. Do not use
+normalized `text` or assume legacy offsets are global.
+
+### Presets, flags and file processing
+
+The seven shipped `chunk_set` names are `chat`, `docstring`, `fiction`, `log`,
+`plain_text`, `scientific_text`, and `technical_text`. Presets live in server
+configuration (`chunk_sets` or `chunk_sets_file`); calls select a name rather
+than define a preset. Explicit request values win over preset defaults. The
+client's `KNOWN_CHUNK_SET_PRESETS` list is advisory: unknown names are forwarded
+for server validation.
+
+Preset `sizes.target_chars` controls merging toward a target, `max_chars`
+controls splitting and `hard_max_chars` is the final cap; merges cannot break
+that cap. These rules preserve `body`; preset `text_transform` changes only
+`text`. Per-call `max_chars` selects exact segmentation and supersedes preset
+size behavior. See the [client option table](svo_client/README.md) for every
+supported flag and omission/default behavior.
+
+`file` acquires and filters a file into prepared texts. `file_chunk` runs file
+acquisition/filtering plus chunking and returns an outbound `transfer_id` for a
+UTF-8 NDJSON artifact. Both support a server-local `filepath`, inline
+`filename` plus `file_content_base64`, or completed upload `transfer_id` plus
+`filename`, with optional `filter_name`. File offsets refer to prepared text,
+not original PDF/HTML bytes. Use the client's file and transfer helpers for
+download size/checksum validation and acknowledgment.
+
+Embedding `model` and positive integer `dimension` must be supplied together or
+both omitted. Omission leaves both fields absent upstream; SVO does not choose
+a default model. Server and standalone client share one version source and
+must be deployed/packaged with equal versions.
+
+See the [client API](svo_client/README.md) and
+[response contract](docs/CHUNK_API_RESPONSE_FORMAT.md) for parsing, item errors,
+offset examples and transfer handling.
+
+### Pipeline
+
+`pipeline --list` lists checks, `pipeline <check-name>` runs one check, and
+`pipeline` runs the complete suite. The pipeline is a thin wrapper over the
+public client: it owns fixtures/assertions and observed side-effect evidence;
+transport, TLS, JSON-RPC, transfer and NDJSON parsing belong to `svo_client`.
+
+- Границы чанков оптимизируются по **максимизации** семантического отклонения между блоком и его 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 <-> строка.