ruts-mcp 0.1.0__tar.gz

ruts_mcp-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.egg-info/
+dist/
+build/
+target/
+
+# Environments
+.venv/
+venv/
+.env
+
+# Tools
+.coverage
+coverage.xml
+.mypy_cache
+.pytest_cache
+.ruff_cache
+
+# Documentation
+site/
+
+# Editors and OS
+.vscode
+.idea
+.DS_Store

ruts_mcp-0.1.0/LICENSE.txt

@@ -0,0 +1,17 @@
+MIT License
+Copyright (c) 2026 Sergey Shkarin
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ruts_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.5
+Name: ruts-mcp
+Version: 0.1.0
+Summary: MCP server for ruTS: statistics of Russian texts as tools for LLM agents
+Project-URL: Homepage, https://github.com/SergeyShk/ruTS-mcp
+Project-URL: Repository, https://github.com/SergeyShk/ruTS-mcp
+Project-URL: Documentation, https://sergeyshk.github.io/ruTS-mcp/
+Project-URL: Issues, https://github.com/SergeyShk/ruTS-mcp/issues
+Author-email: Sergey Shkarin <kouki.sergey@gmail.com>
+Maintainer-email: Sergey Shkarin <kouki.sergey@gmail.com>
+License-Expression: MIT
+License-File: LICENSE.txt
+Keywords: LLM,MCP,NLP,agents,model context protocol,readability,russian,statistics,text
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: Russian
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: fastmcp<5,>=4
+Requires-Dist: platformdirs>=4
+Requires-Dist: ruts<0.17,>=0.16
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/SergeyShk/ruTS-mcp/master/docs/img/ruts-mcp.png" alt="ruTS-mcp" width="480">
+</p>
+
+<h1 align="center">ruTS-mcp</h1>
+
+<p align="center">
+  <b>MCP-сервер для <a href="https://github.com/SergeyShk/ruTS">ruTS</a></b> - статистики русского текста как инструменты для LLM-агентов
+</p>
+
+<p align="center">
+  <a href="https://sergeyshk.github.io/ruTS-mcp/">Документация</a> ·
+  <a href="https://pypi.org/project/ruts-mcp/">PyPI</a> ·
+  <a href="https://github.com/SergeyShk/ruTS-mcp/blob/master/README.en.md">English</a>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/ruts-mcp/"><img src="https://img.shields.io/pypi/v/ruts-mcp?logo=pypi&logoColor=FFE873" alt="Версия"></a>
+  <a href="https://pypi.org/project/ruts-mcp/"><img src="https://img.shields.io/pypi/pyversions/ruts-mcp.svg?logo=python&logoColor=FFE873" alt="Поддерживаемые версии Python"></a>
+  <a href="https://github.com/SergeyShk/ruTS-mcp/actions/workflows/ci.yml"><img src="https://github.com/SergeyShk/ruTS-mcp/actions/workflows/ci.yml/badge.svg" alt="Сборка"></a>
+  <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
+  <a href="https://github.com/SergeyShk/ruTS-mcp/blob/master/LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="Лицензия"></a>
+</p>
+
+---
+
+**ruTS-mcp** дает LLM-агенту инструменты библиотеки [ruTS](https://github.com/SergeyShk/ruTS), чтобы измерить русский текст, а не оценивать его на глаз. Каждое значение приходит вместе с описанием, прочтением по шкале, если она есть, и предупреждениями, когда значение неустойчиво или не имеет смысла для текста.
+
+* **[`analyze_text`](https://sergeyshk.github.io/ruTS-mcp/tools/#analyze_text)** - статистики текста по группам: базовые, удобочитаемость с классом и возрастом читателя, лексическое разнообразие, морфология, фоностатистики, связность, стиль и канцелярит, лексическая сложность, стих, синтаксис
+* **[`kwic`](https://sergeyshk.github.io/ruTS-mcp/tools/#kwic)** - вхождения слова или словосочетания с контекстом
+* **[`collocations`](https://sergeyshk.github.io/ruTS-mcp/tools/#collocations)** - устойчивые сочетания и сочетаемость слова
+* **[`dispersion`](https://sergeyshk.github.io/ruTS-mcp/tools/#dispersion)** - насколько равномерно слова распределены по тексту
+* **[`keyness`](https://sergeyshk.github.io/ruTS-mcp/tools/#keyness)** - ключевые слова относительно русского языка или другого текста
+* **[`compare_texts`](https://sergeyshk.github.io/ruTS-mcp/tools/#compare_texts)** - чем различаются два корпуса текстов по признакам стиля
+* **[Ресурсы и промпты](https://sergeyshk.github.io/ruTS-mcp/resources/)** - шкалы удобочитаемости и нормы стиля, готовые разборы: удобочитаемость, канцелярит, стихотворение, SEO-проверка, сравнение двух текстов
+
+## Установка
+
+Сервер запускается через `uvx` из [uv](https://docs.astral.sh/uv/getting-started/installation/), который сам скачает пакет и Python. Подключение к Claude Code:
+
+```bash
+claude mcp add ruts -- uvx ruts-mcp
+```
+
+Для групп `lexical`, `verse` и `syntax` нужны словари и модель spaCy, их скачивает одна команда:
+
+```bash
+uvx ruts-mcp download
+```
+
+Подключение к Claude Desktop, Cursor и другим клиентам и настройки - в [документации](https://sergeyshk.github.io/ruTS-mcp/installation/).
+
+## Лицензия
+
+[MIT](https://github.com/SergeyShk/ruTS-mcp/blob/master/LICENSE.txt). Словари, которые скачивает `ruts-mcp download`, распространяются на условиях их авторов: [частотный словарь](http://dict.ruslang.ru/freq.php) Ляшевской и Шарова, [словарь ударений](https://github.com/Koziev/NLP_Datasets) Козиева (CC0), [модель spaCy](https://github.com/explosion/spacy-models) (MIT).

ruts_mcp-0.1.0/README.en.md

@@ -0,0 +1,55 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/SergeyShk/ruTS-mcp/master/docs/img/ruts-mcp.png" alt="ruTS-mcp" width="480">
+</p>
+
+<h1 align="center">ruTS-mcp</h1>
+
+<p align="center">
+  <b>MCP server for <a href="https://github.com/SergeyShk/ruTS">ruTS</a></b> - statistics of Russian texts as tools for LLM agents
+</p>
+
+<p align="center">
+  <a href="https://sergeyshk.github.io/ruTS-mcp/en/">Documentation</a> ·
+  <a href="https://pypi.org/project/ruts-mcp/">PyPI</a> ·
+  <a href="https://github.com/SergeyShk/ruTS-mcp/blob/master/README.md">Русский</a>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/ruts-mcp/"><img src="https://img.shields.io/pypi/v/ruts-mcp?logo=pypi&logoColor=FFE873" alt="Version"></a>
+  <a href="https://pypi.org/project/ruts-mcp/"><img src="https://img.shields.io/pypi/pyversions/ruts-mcp.svg?logo=python&logoColor=FFE873" alt="Supported Python versions"></a>
+  <a href="https://github.com/SergeyShk/ruTS-mcp/actions/workflows/ci.yml"><img src="https://github.com/SergeyShk/ruTS-mcp/actions/workflows/ci.yml/badge.svg" alt="Build"></a>
+  <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
+  <a href="https://github.com/SergeyShk/ruTS-mcp/blob/master/LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License"></a>
+</p>
+
+---
+
+**ruTS-mcp** gives an LLM agent the tools of the [ruTS](https://github.com/SergeyShk/ruTS) library to measure a Russian text instead of judging it by eye. Every value comes with a description, a reading by a scale where there is one, and warnings when the value is unstable or meaningless for the text. The server answers in Russian.
+
+* **[`analyze_text`](https://sergeyshk.github.io/ruTS-mcp/en/tools/#analyze_text)** - statistics of a text by groups: basic, readability with the grade and age of the reader, lexical diversity, morphology, phonetics, cohesion, style and officialese, lexical sophistication, verse, syntax
+* **[`kwic`](https://sergeyshk.github.io/ruTS-mcp/en/tools/#kwic)** - occurrences of a word or a phrase with their context
+* **[`collocations`](https://sergeyshk.github.io/ruTS-mcp/en/tools/#collocations)** - set phrases and the collocates of a word
+* **[`dispersion`](https://sergeyshk.github.io/ruTS-mcp/en/tools/#dispersion)** - how evenly words are spread over the text
+* **[`keyness`](https://sergeyshk.github.io/ruTS-mcp/en/tools/#keyness)** - keywords against the Russian language or another text
+* **[`compare_texts`](https://sergeyshk.github.io/ruTS-mcp/en/tools/#compare_texts)** - how two corpora of texts differ by style features
+* **[Resources and prompts](https://sergeyshk.github.io/ruTS-mcp/en/resources/)** - readability scales and style norms, ready reviews: readability, officialese, a poem, an SEO check, a comparison of two texts
+
+## Installation
+
+The server runs with `uvx` from [uv](https://docs.astral.sh/uv/getting-started/installation/), which downloads the package and Python itself. Connecting to Claude Code:
+
+```bash
+claude mcp add ruts -- uvx ruts-mcp
+```
+
+The `lexical`, `verse` and `syntax` groups need dictionaries and a spaCy model; one command downloads them:
+
+```bash
+uvx ruts-mcp download
+```
+
+Connecting to Claude Desktop, Cursor and other clients and the settings are in the [documentation](https://sergeyshk.github.io/ruTS-mcp/en/installation/).
+
+## License
+
+[MIT](https://github.com/SergeyShk/ruTS-mcp/blob/master/LICENSE.txt). The dictionaries that `ruts-mcp download` fetches are distributed on the terms of their authors: the [frequency dictionary](http://dict.ruslang.ru/freq.php) of Lyashevskaya and Sharoff, the [stress dictionary](https://github.com/Koziev/NLP_Datasets) of Koziev (CC0), the [spaCy model](https://github.com/explosion/spacy-models) (MIT).

ruts_mcp-0.1.0/README.md

@@ -0,0 +1,55 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/SergeyShk/ruTS-mcp/master/docs/img/ruts-mcp.png" alt="ruTS-mcp" width="480">
+</p>
+
+<h1 align="center">ruTS-mcp</h1>
+
+<p align="center">
+  <b>MCP-сервер для <a href="https://github.com/SergeyShk/ruTS">ruTS</a></b> - статистики русского текста как инструменты для LLM-агентов
+</p>
+
+<p align="center">
+  <a href="https://sergeyshk.github.io/ruTS-mcp/">Документация</a> ·
+  <a href="https://pypi.org/project/ruts-mcp/">PyPI</a> ·
+  <a href="https://github.com/SergeyShk/ruTS-mcp/blob/master/README.en.md">English</a>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/ruts-mcp/"><img src="https://img.shields.io/pypi/v/ruts-mcp?logo=pypi&logoColor=FFE873" alt="Версия"></a>
+  <a href="https://pypi.org/project/ruts-mcp/"><img src="https://img.shields.io/pypi/pyversions/ruts-mcp.svg?logo=python&logoColor=FFE873" alt="Поддерживаемые версии Python"></a>
+  <a href="https://github.com/SergeyShk/ruTS-mcp/actions/workflows/ci.yml"><img src="https://github.com/SergeyShk/ruTS-mcp/actions/workflows/ci.yml/badge.svg" alt="Сборка"></a>
+  <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
+  <a href="https://github.com/SergeyShk/ruTS-mcp/blob/master/LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="Лицензия"></a>
+</p>
+
+---
+
+**ruTS-mcp** дает LLM-агенту инструменты библиотеки [ruTS](https://github.com/SergeyShk/ruTS), чтобы измерить русский текст, а не оценивать его на глаз. Каждое значение приходит вместе с описанием, прочтением по шкале, если она есть, и предупреждениями, когда значение неустойчиво или не имеет смысла для текста.
+
+* **[`analyze_text`](https://sergeyshk.github.io/ruTS-mcp/tools/#analyze_text)** - статистики текста по группам: базовые, удобочитаемость с классом и возрастом читателя, лексическое разнообразие, морфология, фоностатистики, связность, стиль и канцелярит, лексическая сложность, стих, синтаксис
+* **[`kwic`](https://sergeyshk.github.io/ruTS-mcp/tools/#kwic)** - вхождения слова или словосочетания с контекстом
+* **[`collocations`](https://sergeyshk.github.io/ruTS-mcp/tools/#collocations)** - устойчивые сочетания и сочетаемость слова
+* **[`dispersion`](https://sergeyshk.github.io/ruTS-mcp/tools/#dispersion)** - насколько равномерно слова распределены по тексту
+* **[`keyness`](https://sergeyshk.github.io/ruTS-mcp/tools/#keyness)** - ключевые слова относительно русского языка или другого текста
+* **[`compare_texts`](https://sergeyshk.github.io/ruTS-mcp/tools/#compare_texts)** - чем различаются два корпуса текстов по признакам стиля
+* **[Ресурсы и промпты](https://sergeyshk.github.io/ruTS-mcp/resources/)** - шкалы удобочитаемости и нормы стиля, готовые разборы: удобочитаемость, канцелярит, стихотворение, SEO-проверка, сравнение двух текстов
+
+## Установка
+
+Сервер запускается через `uvx` из [uv](https://docs.astral.sh/uv/getting-started/installation/), который сам скачает пакет и Python. Подключение к Claude Code:
+
+```bash
+claude mcp add ruts -- uvx ruts-mcp
+```
+
+Для групп `lexical`, `verse` и `syntax` нужны словари и модель spaCy, их скачивает одна команда:
+
+```bash
+uvx ruts-mcp download
+```
+
+Подключение к Claude Desktop, Cursor и другим клиентам и настройки - в [документации](https://sergeyshk.github.io/ruTS-mcp/installation/).
+
+## Лицензия
+
+[MIT](https://github.com/SergeyShk/ruTS-mcp/blob/master/LICENSE.txt). Словари, которые скачивает `ruts-mcp download`, распространяются на условиях их авторов: [частотный словарь](http://dict.ruslang.ru/freq.php) Ляшевской и Шарова, [словарь ударений](https://github.com/Koziev/NLP_Datasets) Козиева (CC0), [модель spaCy](https://github.com/explosion/spacy-models) (MIT).

ruts_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,168 @@
+[project]
+name = "ruts-mcp"
+version = "0.1.0"
+description = "MCP server for ruTS: statistics of Russian texts as tools for LLM agents"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE.txt"]
+authors = [{ name = "Sergey Shkarin", email = "kouki.sergey@gmail.com" }]
+maintainers = [{ name = "Sergey Shkarin", email = "kouki.sergey@gmail.com" }]
+keywords = [
+    "MCP",
+    "model context protocol",
+    "LLM",
+    "agents",
+    "NLP",
+    "text",
+    "statistics",
+    "readability",
+    "russian",
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "Intended Audience :: Information Technology",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Text Processing",
+    "Topic :: Text Processing :: Linguistic",
+    "Typing :: Typed",
+    "Natural Language :: Russian",
+]
+dependencies = [
+    "fastmcp>=4,<5",
+    "platformdirs>=4",
+    "ruts>=0.16,<0.17",
+]
+
+[project.scripts]
+ruts-mcp = "ruts_mcp.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/SergeyShk/ruTS-mcp"
+Repository = "https://github.com/SergeyShk/ruTS-mcp"
+Documentation = "https://sergeyshk.github.io/ruTS-mcp/"
+Issues = "https://github.com/SergeyShk/ruTS-mcp/issues"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["ruts_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/ruts_mcp", "/README.md", "/README.en.md", "/LICENSE.txt"]
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true
+
+[dependency-groups]
+test = ["pytest>=8.3", "pytest-cov>=6.0", "ru-core-news-sm"]
+lint = ["mypy>=1.14", "pre-commit>=4.0", "ruff>=0.9"]
+docs = [
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.5",
+    "mkdocs-static-i18n>=1.2",
+    "pymdown-extensions>=10.0",
+]
+dev = [
+    { include-group = "test" },
+    { include-group = "lint" },
+    { include-group = "docs" },
+]
+
+[tool.uv.sources]
+ru-core-news-sm = { url = "https://github.com/explosion/spacy-models/releases/download/ru_core_news_sm-3.8.0/ru_core_news_sm-3.8.0-py3-none-any.whl" }
+
+[tool.ruff]
+target-version = "py311"
+line-length = 99
+src = ["ruts_mcp", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "A",    # flake8-builtins
+    "B",    # flake8-bugbear
+    "C4",   # flake8-comprehensions
+    "C90",  # mccabe
+    "E",    # pycodestyle errors
+    "F",    # pyflakes
+    "I",    # isort
+    "N",    # pep8-naming
+    "PERF", # perflint
+    "PTH",  # flake8-use-pathlib
+    "Q",    # flake8-quotes
+    "RET",  # flake8-return
+    "RUF",  # ruff-specific
+    "SIM",  # flake8-simplify
+    "UP",   # pyupgrade
+    "W",    # pycodestyle warnings
+]
+ignore = [
+    "E501",
+    "RUF001",
+    "RUF002",
+    "RUF003",
+]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 18
+
+[tool.ruff.lint.isort]
+known-first-party = ["ruts_mcp"]
+combine-as-imports = true
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["N801", "N802"]
+
+[tool.mypy]
+python_version = "3.11"
+files = ["ruts_mcp"]
+pretty = true
+show_traceback = true
+color_output = true
+allow_redefinition = false
+check_untyped_defs = true
+disallow_any_generics = true
+disallow_incomplete_defs = true
+ignore_missing_imports = true
+implicit_reexport = false
+no_implicit_optional = true
+show_column_numbers = true
+show_error_codes = true
+show_error_context = true
+strict_equality = true
+strict_optional = true
+warn_no_return = true
+warn_redundant_casts = true
+warn_return_any = true
+warn_unreachable = true
+warn_unused_configs = true
+warn_unused_ignores = true
+
+[tool.pytest.ini_options]
+addopts = "-v --strict-markers --strict-config --doctest-modules"
+testpaths = ["tests", "ruts_mcp"]
+doctest_optionflags = ["NORMALIZE_WHITESPACE", "ELLIPSIS"]
+
+[tool.coverage.run]
+source = ["ruts_mcp"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 100
+show_missing = true
+exclude_also = ["if TYPE_CHECKING:", "raise NotImplementedError"]

ruts_mcp-0.1.0/ruts_mcp/__init__.py

@@ -0,0 +1,18 @@
+# MCP-сервер Russian Texts Statistics (ruTS-mcp)
+#
+# Copyright (C) 2026
+# Автор: Шкарин Сергей <kouki.sergey@gmail.com>
+# URL: <https://github.com/SergeyShk/ruTS-mcp>
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("ruts-mcp")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+__description__ = """MCP-сервер для ruTS: статистики русского текста как инструменты для LLM-агентов.
+Требует версию Python 3.11 и выше"""
+__author__ = "Шкарин Сергей"
+__author_email__ = "kouki.sergey@gmail.com"
+
+__all__ = ["__version__"]

ruts_mcp-0.1.0/ruts_mcp/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

ruts_mcp-0.1.0/ruts_mcp/analysis.py

@@ -0,0 +1,137 @@
+import math
+from dataclasses import dataclass
+from functools import cached_property
+from typing import TYPE_CHECKING, Any, Literal
+
+if TYPE_CHECKING:
+    from ruts import BasicStats
+
+Preset = Literal["plainrussian", "fiction", "academic"]
+GroupResult = tuple[dict[str, Any], list[str]]
+
+SIGNIFICANT_DIGITS = 4
+# Группы lexical и verse не считают числа словами, остальные считают
+NO_WORDS_WARNING = "Группа {group} не посчитана: в тексте нет слов, а числа словами не считаются"
+
+
+@dataclass(frozen=True)
+class Options:
+    """
+    Настройки групп статистик
+
+    Атрибуты:
+        distributions (bool): Добавить распределения в группу basic
+        preset (str): Пресет коэффициентов формул удобочитаемости ruTS
+    """
+
+    distributions: bool = False
+    preset: Preset = "plainrussian"
+
+
+class Analysis:
+    """
+    Текст с настройками и объектами ruTS, общими для групп статистик
+
+    Описание:
+        Базовые статистики нужны группам basic и readability, поэтому они
+        считаются один раз за вызов инструмента, при первом обращении
+
+    Аргументы:
+        text (str): Текст на русском языке
+        options (Options): Настройки групп; None - по умолчанию
+
+    Атрибуты:
+        text (str): Текст на русском языке
+        options (Options): Настройки групп
+    """
+
+    def __init__(self, text: str, options: Options | None = None) -> None:
+        self.text = text
+        self.options = Options() if options is None else options
+
+    @cached_property
+    def basic(self) -> "BasicStats":
+        """Базовые статистики текста с нормированными долями"""
+        from ruts import BasicStats
+
+        return BasicStats(self.text, normalize=True)
+
+
+def clean(value: Any) -> Any:
+    """
+    Значение статистики, готовое для JSON
+
+    Описание:
+        Дробное число округляется до четырех значащих цифр; nan и бесконечность,
+        которых нет в JSON, становятся None. Остальные значения не меняются
+
+    Аргументы:
+        value (Any): Значение статистики ruTS
+
+    Вывод:
+        Any: Значение для ответа инструмента
+
+    Пример использования:
+        >>> clean(0.0061549), clean(1771.13), clean(float("nan")), clean(7)
+        (0.006155, 1771.0, None, 7)
+    """
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            return None
+        return float(f"{value:.{SIGNIFICANT_DIGITS}g}")
+    return value
+
+
+def stat(
+    value: Any,
+    description: str,
+    share: float | None = None,
+    interpretation: str | None = None,
+    details: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """
+    Статистика в ответе инструмента
+
+    Аргументы:
+        value (Any): Значение статистики
+        description (str): Что считает статистика
+        share (float): Доля от всех слов или символов; None - без доли
+        interpretation (str): Прочтение значения по шкале; None - без шкалы
+        details (dict[str, Any]): Другие ключи статистики перед описанием
+
+    Вывод:
+        dict[str, Any]: Значение, доля, прочтение, другие ключи и описание
+
+    Пример использования:
+        >>> stat(0.85714, "Доля", interpretation="высокая")
+        {'value': 0.8571, 'interpretation': 'высокая', 'description': 'Доля'}
+    """
+    item: dict[str, Any] = {"value": clean(value)}
+    if share is not None:
+        item["share"] = clean(share)
+    if interpretation is not None:
+        item["interpretation"] = interpretation
+    item |= details or {}
+    item["description"] = description
+    return item
+
+
+def undefined_warnings(stats: dict[str, dict[str, Any]], reason: str) -> list[str]:
+    """
+    Предупреждение о статистиках, не определенных на тексте
+
+    Аргументы:
+        stats (dict[str, dict[str, Any]]): Статистики группы
+        reason (str): Почему значения не определены
+
+    Вывод:
+        list[str]: Предупреждение со списком статистик со значением None или пустой список
+
+    Пример использования:
+        >>> undefined_warnings({"hdd": {"value": None}, "ttr": {"value": 1.0}}, "текст короткий")
+        ['Не определены на этом тексте: hdd - текст короткий']
+    """
+    names = [name for name, item in stats.items() if item["value"] is None]
+    if not names:
+        return []
+    return [f"Не определены на этом тексте: {', '.join(names)} - {reason}"]