Клиент к ИИ-платформе REG.RU

Обёртка над ai.reg.cloud. Протокол совместим с OpenAI, но у платформы свои
особенности: ключ бывает открыт не ко всем моделям, отказ приходит отдельным
кодом, картинки и речь доступны не всем.

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

Claude-Session: https://claude.ai/code/session_01Loz5stgQZH6ofBdMqTxiJu

README.md

@@ -0,0 +1,85 @@
+# regcloud-ai
+
+Клиент к ИИ-платформе REG.RU, домен `ai.reg.cloud`.
+
+Протокол там совместим с OpenAI, но есть особенности, ради которых и написана обёртка.
+Ключ бывает открыт не ко всем моделям, отказ приходит отдельным кодом, а список
+доступного удобно спрашивать заранее. Плюс тут же лежат мелочи, которые всё равно
+приходится писать в каждом проекте: ремонт оборванного json, чистка типографики
+и отлов иероглифов, которые модели иногда роняют в русский текст.
+
+## Установка
+
+```bash
+pip install httpx
+# дальше просто положить пакет рядом или поставить из этого репозитория
+pip install git+https://git.stackworks.ru/viktor/regcloud-ai.git
+```
+
+## Как пользоваться
+
+```python
+from regcloud_ai import RegCloudAI
+
+ai = RegCloudAI()                      # ключ берётся из REGCLOUD_AI_KEY
+print(ai.ask("Объясни в двух словах, что такое трансформер"))
+```
+
+Ответ приходит объектом, где кроме текста лежит расход токенов и время.
+
+```python
+answer = ai.chat("Напиши заголовок ролика про нейросети", model="qwen3.7-max")
+print(answer.text, answer.usage.total_tokens, answer.seconds)
+```
+
+Каскад на случай, если модель закрыта для ключа или занята.
+
+```python
+answer = ai.cascade("Твой запрос", models=["claude-5-sonnet", "gpt-5.5", "qwen3.7-max"])
+```
+
+Асинхронно всё то же самое.
+
+```python
+from regcloud_ai import AsyncRegCloudAI
+
+async with AsyncRegCloudAI() as ai:
+    print(await ai.ask("Привет"))
+```
+
+## Что доступно на платформе
+
+На август 2026 платформа отдаёт двадцать девять моделей, среди них claude-5-sonnet,
+gpt-5.5, gemini-3.1-pro, grok-4.3, семейства qwen, glm, deepseek, kimi и minimax.
+Точный список всегда спрашивайте у самой платформы.
+
+```python
+print(RegCloudAI().models())
+```
+
+Замечание про доступы. Ключ может быть выдан только на часть моделей. Тогда обращение
+к остальным вернёт `ModelAccessError`. Картинки, синтез и распознавание речи на платформе
+есть, но открываются отдельно, обычному текстовому ключу они недоступны.
+
+## Мелочи, которые обычно нужны
+
+```python
+from regcloud_ai.client import extract_json, normalize, foreign_chars
+
+data = extract_json(answer.text)          # вытащит json даже из оборванного ответа
+text = normalize(answer.text)             # длинные тире и ёлочки станут обычными
+bad = foreign_chars(text)                 # иероглифы, если модель их насыпала
+```
+
+## Замеры
+
+Проверено на живых запросах 23.08.2026, время до полного ответа на коротком запросе.
+
+| Модель | Время |
+|---|---|
+| qwen3.7-max | 2.9 с |
+| deepseek-v4-flash | 4.5 с |
+| gpt-5.5 | 5.3 с |
+| claude-5-sonnet | 5.5 с |
+| gemini-3.5-flash | 5.6 с |
+| glm-5.2 | 7.1 с |