rb-llmkit 0.14.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (142) hide show
  1. rb_llmkit-0.14.2/.gitignore +19 -0
  2. rb_llmkit-0.14.2/.python-version +1 -0
  3. rb_llmkit-0.14.2/LICENSE +21 -0
  4. rb_llmkit-0.14.2/PKG-INFO +185 -0
  5. rb_llmkit-0.14.2/README.md +168 -0
  6. rb_llmkit-0.14.2/pyproject.toml +145 -0
  7. rb_llmkit-0.14.2/src/rb_llmkit/__init__.py +72 -0
  8. rb_llmkit-0.14.2/src/rb_llmkit/_distribution.py +21 -0
  9. rb_llmkit-0.14.2/src/rb_llmkit/_sync.py +24 -0
  10. rb_llmkit-0.14.2/src/rb_llmkit/callutil.py +30 -0
  11. rb_llmkit-0.14.2/src/rb_llmkit/cli/__init__.py +5 -0
  12. rb_llmkit-0.14.2/src/rb_llmkit/cli/app.py +41 -0
  13. rb_llmkit-0.14.2/src/rb_llmkit/cli/ask.py +190 -0
  14. rb_llmkit-0.14.2/src/rb_llmkit/cli/audio.py +82 -0
  15. rb_llmkit-0.14.2/src/rb_llmkit/cli/auth.py +93 -0
  16. rb_llmkit-0.14.2/src/rb_llmkit/cli/chat.py +154 -0
  17. rb_llmkit-0.14.2/src/rb_llmkit/cli/config.py +33 -0
  18. rb_llmkit-0.14.2/src/rb_llmkit/cli/cost.py +77 -0
  19. rb_llmkit-0.14.2/src/rb_llmkit/cli/describe.py +29 -0
  20. rb_llmkit-0.14.2/src/rb_llmkit/cli/doctor.py +32 -0
  21. rb_llmkit-0.14.2/src/rb_llmkit/cli/embeddings.py +29 -0
  22. rb_llmkit-0.14.2/src/rb_llmkit/cli/image.py +36 -0
  23. rb_llmkit-0.14.2/src/rb_llmkit/cli/main.py +60 -0
  24. rb_llmkit-0.14.2/src/rb_llmkit/cli/model.py +70 -0
  25. rb_llmkit-0.14.2/src/rb_llmkit/cli/models.py +68 -0
  26. rb_llmkit-0.14.2/src/rb_llmkit/cli/output.py +241 -0
  27. rb_llmkit-0.14.2/src/rb_llmkit/cli/render.py +115 -0
  28. rb_llmkit-0.14.2/src/rb_llmkit/cli/routing.py +74 -0
  29. rb_llmkit-0.14.2/src/rb_llmkit/cli/runtime.py +94 -0
  30. rb_llmkit-0.14.2/src/rb_llmkit/cli/surface.py +72 -0
  31. rb_llmkit-0.14.2/src/rb_llmkit/cli/video.py +97 -0
  32. rb_llmkit-0.14.2/src/rb_llmkit/cli/web.py +49 -0
  33. rb_llmkit-0.14.2/src/rb_llmkit/config.py +87 -0
  34. rb_llmkit-0.14.2/src/rb_llmkit/contracts/routing-v1.schema.json +80 -0
  35. rb_llmkit-0.14.2/src/rb_llmkit/contracts/routing-v1.vectors.json +116 -0
  36. rb_llmkit-0.14.2/src/rb_llmkit/core.py +376 -0
  37. rb_llmkit-0.14.2/src/rb_llmkit/data_files.py +30 -0
  38. rb_llmkit-0.14.2/src/rb_llmkit/doctor.py +65 -0
  39. rb_llmkit-0.14.2/src/rb_llmkit/errors.py +98 -0
  40. rb_llmkit-0.14.2/src/rb_llmkit/gateway/__init__.py +8 -0
  41. rb_llmkit-0.14.2/src/rb_llmkit/gateway/client.py +247 -0
  42. rb_llmkit-0.14.2/src/rb_llmkit/gateway/parse.py +259 -0
  43. rb_llmkit-0.14.2/src/rb_llmkit/gateway/sse.py +31 -0
  44. rb_llmkit-0.14.2/src/rb_llmkit/health.py +171 -0
  45. rb_llmkit-0.14.2/src/rb_llmkit/keys.py +38 -0
  46. rb_llmkit-0.14.2/src/rb_llmkit/legacy.py +94 -0
  47. rb_llmkit-0.14.2/src/rb_llmkit/models.py +108 -0
  48. rb_llmkit-0.14.2/src/rb_llmkit/opencli.py +243 -0
  49. rb_llmkit-0.14.2/src/rb_llmkit/py.typed +0 -0
  50. rb_llmkit-0.14.2/src/rb_llmkit/routing.py +127 -0
  51. rb_llmkit-0.14.2/src/rb_llmkit/template.py +41 -0
  52. rb_llmkit-0.14.2/src/rb_llmkit/usage.py +124 -0
  53. rb_llmkit-0.14.2/src/rb_llmkit/version.py +18 -0
  54. rb_llmkit-0.14.2/tests/conftest.py +252 -0
  55. rb_llmkit-0.14.2/tests/contracts/data/judge_schema.json +6 -0
  56. rb_llmkit-0.14.2/tests/contracts/data/routing.json +12 -0
  57. rb_llmkit-0.14.2/tests/contracts/data/routing_all_broken.json +13 -0
  58. rb_llmkit-0.14.2/tests/contracts/data/template.md +5 -0
  59. rb_llmkit-0.14.2/tests/contracts/data/template_needs_x.md +1 -0
  60. rb_llmkit-0.14.2/tests/contracts/fixtures.yaml +19 -0
  61. rb_llmkit-0.14.2/tests/contracts/schema.json +89 -0
  62. rb_llmkit-0.14.2/tests/contracts/windmill/llmkit.yaml +68 -0
  63. rb_llmkit-0.14.2/tests/data/contracts/windmill-serp.yaml +106 -0
  64. rb_llmkit-0.14.2/tests/data/gateway_combo.sse +5 -0
  65. rb_llmkit-0.14.2/tests/data/gateway_opencode_go.json +14 -0
  66. rb_llmkit-0.14.2/tests/data/legacy_config.toml +74 -0
  67. rb_llmkit-0.14.2/tests/data/mustache_spec/LICENSE +20 -0
  68. rb_llmkit-0.14.2/tests/data/mustache_spec/README.md +4 -0
  69. rb_llmkit-0.14.2/tests/data/mustache_spec/comments.json +106 -0
  70. rb_llmkit-0.14.2/tests/data/mustache_spec/delimiters.json +132 -0
  71. rb_llmkit-0.14.2/tests/data/mustache_spec/interpolation.json +422 -0
  72. rb_llmkit-0.14.2/tests/data/mustache_spec/inverted.json +227 -0
  73. rb_llmkit-0.14.2/tests/data/mustache_spec/partials.json +153 -0
  74. rb_llmkit-0.14.2/tests/data/mustache_spec/sections.json +423 -0
  75. rb_llmkit-0.14.2/tests/data/opencli.schema.json +350 -0
  76. rb_llmkit-0.14.2/tests/snapshots/describe.json +2929 -0
  77. rb_llmkit-0.14.2/tests/snapshots/help/ask.txt +44 -0
  78. rb_llmkit-0.14.2/tests/snapshots/help/audio-speech.txt +24 -0
  79. rb_llmkit-0.14.2/tests/snapshots/help/audio-transcribe.txt +22 -0
  80. rb_llmkit-0.14.2/tests/snapshots/help/audio-voices.txt +17 -0
  81. rb_llmkit-0.14.2/tests/snapshots/help/audio.txt +14 -0
  82. rb_llmkit-0.14.2/tests/snapshots/help/auth-status.txt +27 -0
  83. rb_llmkit-0.14.2/tests/snapshots/help/auth.txt +13 -0
  84. rb_llmkit-0.14.2/tests/snapshots/help/chat-api.txt +21 -0
  85. rb_llmkit-0.14.2/tests/snapshots/help/chat-count-tokens.txt +21 -0
  86. rb_llmkit-0.14.2/tests/snapshots/help/chat-gemini-models.txt +17 -0
  87. rb_llmkit-0.14.2/tests/snapshots/help/chat-messages.txt +21 -0
  88. rb_llmkit-0.14.2/tests/snapshots/help/chat-responses-compact.txt +21 -0
  89. rb_llmkit-0.14.2/tests/snapshots/help/chat-responses.txt +21 -0
  90. rb_llmkit-0.14.2/tests/snapshots/help/chat-systemone.txt +21 -0
  91. rb_llmkit-0.14.2/tests/snapshots/help/chat.txt +19 -0
  92. rb_llmkit-0.14.2/tests/snapshots/help/config-show.txt +15 -0
  93. rb_llmkit-0.14.2/tests/snapshots/help/config.txt +12 -0
  94. rb_llmkit-0.14.2/tests/snapshots/help/cost.txt +20 -0
  95. rb_llmkit-0.14.2/tests/snapshots/help/describe.txt +16 -0
  96. rb_llmkit-0.14.2/tests/snapshots/help/doctor.txt +16 -0
  97. rb_llmkit-0.14.2/tests/snapshots/help/embeddings-create.txt +21 -0
  98. rb_llmkit-0.14.2/tests/snapshots/help/embeddings.txt +12 -0
  99. rb_llmkit-0.14.2/tests/snapshots/help/image-generate.txt +25 -0
  100. rb_llmkit-0.14.2/tests/snapshots/help/image.txt +12 -0
  101. rb_llmkit-0.14.2/tests/snapshots/help/json.txt +44 -0
  102. rb_llmkit-0.14.2/tests/snapshots/help/model-info.txt +17 -0
  103. rb_llmkit-0.14.2/tests/snapshots/help/model-list.txt +17 -0
  104. rb_llmkit-0.14.2/tests/snapshots/help/model-show.txt +20 -0
  105. rb_llmkit-0.14.2/tests/snapshots/help/model.txt +14 -0
  106. rb_llmkit-0.14.2/tests/snapshots/help/models.txt +19 -0
  107. rb_llmkit-0.14.2/tests/snapshots/help/render.txt +22 -0
  108. rb_llmkit-0.14.2/tests/snapshots/help/routing-import.txt +23 -0
  109. rb_llmkit-0.14.2/tests/snapshots/help/routing-validate.txt +23 -0
  110. rb_llmkit-0.14.2/tests/snapshots/help/routing.txt +13 -0
  111. rb_llmkit-0.14.2/tests/snapshots/help/video-edit.txt +23 -0
  112. rb_llmkit-0.14.2/tests/snapshots/help/video-extend.txt +23 -0
  113. rb_llmkit-0.14.2/tests/snapshots/help/video-generate.txt +22 -0
  114. rb_llmkit-0.14.2/tests/snapshots/help/video-get.txt +20 -0
  115. rb_llmkit-0.14.2/tests/snapshots/help/video.txt +15 -0
  116. rb_llmkit-0.14.2/tests/snapshots/help/web-fetch.txt +20 -0
  117. rb_llmkit-0.14.2/tests/snapshots/help/web-search.txt +21 -0
  118. rb_llmkit-0.14.2/tests/snapshots/help/web.txt +13 -0
  119. rb_llmkit-0.14.2/tests/test_api_surface.py +174 -0
  120. rb_llmkit-0.14.2/tests/test_chain.py +56 -0
  121. rb_llmkit-0.14.2/tests/test_cli.py +276 -0
  122. rb_llmkit-0.14.2/tests/test_config.py +92 -0
  123. rb_llmkit-0.14.2/tests/test_contract_runner.py +256 -0
  124. rb_llmkit-0.14.2/tests/test_contracts.py +386 -0
  125. rb_llmkit-0.14.2/tests/test_core.py +73 -0
  126. rb_llmkit-0.14.2/tests/test_cost.py +167 -0
  127. rb_llmkit-0.14.2/tests/test_cost_dates.py +62 -0
  128. rb_llmkit-0.14.2/tests/test_deps.py +66 -0
  129. rb_llmkit-0.14.2/tests/test_describe.py +243 -0
  130. rb_llmkit-0.14.2/tests/test_detach.py +105 -0
  131. rb_llmkit-0.14.2/tests/test_doctor.py +112 -0
  132. rb_llmkit-0.14.2/tests/test_gateway.py +190 -0
  133. rb_llmkit-0.14.2/tests/test_health.py +177 -0
  134. rb_llmkit-0.14.2/tests/test_help.py +303 -0
  135. rb_llmkit-0.14.2/tests/test_keys.py +65 -0
  136. rb_llmkit-0.14.2/tests/test_legacy.py +53 -0
  137. rb_llmkit-0.14.2/tests/test_media.py +154 -0
  138. rb_llmkit-0.14.2/tests/test_render_cli.py +182 -0
  139. rb_llmkit-0.14.2/tests/test_routing.py +98 -0
  140. rb_llmkit-0.14.2/tests/test_routing_default.py +123 -0
  141. rb_llmkit-0.14.2/tests/test_template.py +102 -0
  142. rb_llmkit-0.14.2/tests/test_usage.py +85 -0
@@ -0,0 +1,19 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ build/
6
+ dist/
7
+ .pytest_cache/
8
+ .ruff_cache/
9
+ .coverage
10
+ htmlcov/
11
+ # рабочая копия и результаты mutmut (uv run --group mutation mutmut run)
12
+ mutants/
13
+
14
+ # uv / окружение
15
+ .venv/
16
+ .DS_Store
17
+ Thumbs.db
18
+ .pdm-build/
19
+ .cache/
@@ -0,0 +1 @@
1
+ 3.11
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Roman Bolandau
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,185 @@
1
+ Metadata-Version: 2.5
2
+ Name: rb-llmkit
3
+ Version: 0.14.2
4
+ Summary: Shared LLM layer: model calls through a gateway with typed answers and spend accounting.
5
+ Project-URL: Repository, https://homeserver.tailee01ab.ts.net:3000/bolandeu/llmkit
6
+ Author: Roman Bolandau
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ Requires-Python: >=3.11
10
+ Requires-Dist: combustache==3.0.1
11
+ Requires-Dist: httpx>=0.27
12
+ Requires-Dist: platformdirs>=4
13
+ Requires-Dist: pydantic>=2
14
+ Requires-Dist: rich>=13
15
+ Requires-Dist: typer<0.29,>=0.27
16
+ Description-Content-Type: text/markdown
17
+
18
+ # llmkit
19
+
20
+ Надстройка над шлюзом [9router](https://github.com/decolua/9router): вызовы моделей,
21
+ JSON по схеме и пачка задач — через шлюз, без своих клиентов провайдеров.
22
+ Даёт `LlmKit` в Python и команду `llm` для людей и агентов.
23
+
24
+ Своего состояния у llmkit нет: ни базы, ни журнала, ни хранения ключей. Доступ к
25
+ моделям, подписки, квоты и расходы — у шлюза (ADR-0001). Нужен запущенный 9router
26
+ на той же машине.
27
+
28
+ Статус — [CHANGELOG.md](CHANGELOG.md).
29
+
30
+ ## Что это даёт
31
+
32
+ | Возможность | Коротко |
33
+ |---|---|
34
+ | Один вызов модели | `LlmKit.ask` / `generate`; цепочку, фолбэк и повторы исполняет шлюз |
35
+ | JSON по схеме | JSON Schema уходит в шлюз как `response_format`; невалидный ответ повторяется с текстом ошибки |
36
+ | Пачка задач | `ask_many` с ограничением параллельности, падение одной задачи не рвёт пачку |
37
+ | Вся поверхность шлюза | команды `llm image`, `audio`, `video`, `embeddings`, `web`, `model`, `chat` — по одной на семейство эндпоинтов |
38
+ | Расходы | `llm cost` читает журнал шлюза (`usageHistory`) только на чтение, по ключам потребителей |
39
+
40
+ ## Установка
41
+
42
+ Дистрибутив называется **`rb-llmkit`**, импорт — `llmkit`, команда — `llm`.
43
+ Ставить всегда по тегу `vX.Y.Z`.
44
+
45
+ ```bash
46
+ uv add "rb-llmkit @ git+https://github.com/bolandeu/llmkit@vX.Y.Z" # в проект
47
+ uv tool install "rb-llmkit @ git+https://github.com/bolandeu/llmkit@vX.Y.Z" # команда в систему
48
+ ```
49
+
50
+ Репозиторий приватный: на машине нужен доступ к GitHub (`gh auth login` или
51
+ ssh-ключ и адрес `git+ssh://git@github.com/bolandeu/llmkit`). Требуется Python >= 3.11.
52
+
53
+ ## Ключ шлюза и routing
54
+
55
+ Ключ берётся только из окружения; имя переменной называет routing (`key_env`).
56
+ Нет переменной — код 3, `AUTH_MISSING` с её именем.
57
+
58
+ ```bash
59
+ export NINEROUTER_API_KEY=sk-...
60
+ ```
61
+
62
+ Провайдер шлюза и цепочка моделей приходят данными — routing v1 (схема
63
+ `src/rb_llmkit/contracts/routing-v1.schema.json`). Секретов в routing нет.
64
+
65
+ ```json
66
+ {
67
+ "providers": {
68
+ "9router": {"protocol": "openai_compatible", "base_url": "http://localhost:20128/v1",
69
+ "key_env": "NINEROUTER_API_KEY"}
70
+ },
71
+ "chain": ["Deep Sec", "opencode-go"]
72
+ }
73
+ ```
74
+
75
+ - `protocol` — только `openai_compatible` с адресом шлюза.
76
+ - `chain` — имена моделей шлюза строками, как в его настройке (комбо — одна
77
+ строка). Порядок и фолбэк исполняет шлюз: llmkit просит первую.
78
+ - CLI: `--routing '<json>'` или `--routing <файл>`; без него — `LLMKIT_ROUTING_FILE`;
79
+ без него — `routing.json` в каталоге конфигурации (`platformdirs.user_config_dir("llmkit")`,
80
+ macOS — `~/Library/Application Support/llmkit/routing.json`). Нет ничего — код 2,
81
+ `ROUTING_MISSING` с путём по умолчанию.
82
+ - Цепочку можно задать `-m` (повторяемый) в routing без `chain`; оба сразу —
83
+ `ROUTING_INVALID` «chain задана дважды».
84
+
85
+ ## CLI `llm`
86
+
87
+ У всех команд есть `--json` (конверт в stdout), диагностика идёт в stderr.
88
+ Коды выхода: **0** — успех, **1** — непредвиденная ошибка, **2** — неверные
89
+ аргументы или routing, **3** — нет переменной с ключом шлюза, **5** — шлюз
90
+ недоступен, ответил ошибкой или его журнал расходов не читается.
91
+
92
+ ```bash
93
+ llm # справка: список команд, код выхода 0
94
+ llm ask "Столица Франции?" --routing routing.json
95
+ llm ask "Привет" -m "Deep Sec" -m opencode-go # цепочка из CLI, если в routing нет chain
96
+ llm json "Разбери запрос" --schema schema.json # в stdout только JSON-объект
97
+ llm render --template prompt.md --vars vars.json # шаблон mustache; нет переменной — код 2
98
+ llm models --json # провайдеры routing, источник ключа, цепочка
99
+ llm routing validate routing.json # проверка перед сохранением; ROUTING_INVALID с путём к полю
100
+ llm routing import config.toml # перенос config.toml llmkit < 0.8
101
+ llm auth status --check --json # ключ шлюза: откуда и работает ли; 3 — ключ не принят
102
+ llm cost --since 7d --json # расходы из журнала шлюза, по ключам
103
+ llm config show --json # итоговые настройки вызова
104
+ llm doctor --json # готовность: версия, конфиг, routing, шлюз
105
+ llm describe --json # контракт CLI документом OpenCLI
106
+ ```
107
+
108
+ ### Поверхность шлюза
109
+
110
+ Одна команда — один эндпоинт шлюза; ответ типизирован в `--json`, форматы
111
+ провайдера llmkit не разбирает.
112
+
113
+ ```bash
114
+ llm image generate "кот в шляпе" -m openai/gpt-image-1 --out cat.png --json
115
+ llm audio speech "привет" -m openai/gpt-4o-mini-tts --voice alloy --out speech.mp3 --json
116
+ llm audio transcribe speech.mp3 -m openai/whisper-1 --json
117
+ llm audio voices --json
118
+ llm video generate "волна на пляже" -m google/veo-3 --json
119
+ llm video get video_1 --json
120
+ llm embeddings create "текст" -m openai/text-embedding-3-small --json
121
+ llm web search "llmkit" -m perplexity/sonar --json
122
+ llm web fetch https://example.com --json
123
+ llm model list --json
124
+ llm model show deepseek/deepseek-v4.1-flash-1017 --json
125
+ llm chat responses "Столица Франции?" -m openai/gpt-5 --json
126
+ llm chat messages "Столица Франции?" -m anthropic/claude-x --json
127
+ ```
128
+
129
+ Картинка и речь приходят байтами — их место в файле `--out`; ссылку или URL
130
+ `--json` отдаёт в поле `url`.
131
+
132
+ ## Как агент работает с CLI
133
+
134
+ 1. `llm --help` и `llm <команда> --help` — справка из кода: у каждой команды есть
135
+ строка `Example:`, у каждого флага `help=`.
136
+ 2. `--json` — машинный конверт в stdout: `{"ok": true, ...}` или
137
+ `{"ok": false, "error": {"code", "message", "action"}}`.
138
+ 3. Коды выхода говорят, что делать: 0 — готово, 2 — аргументы, 3 — ключ, 5 — шлюз.
139
+ 4. `llm doctor --json` — готовность до работы; `llm describe --json` — контракт
140
+ CLI для каталога инструментов.
141
+
142
+ ## Расходы
143
+
144
+ `llm cost` читает SQLite шлюза: `LLMKIT_GATEWAY_DB`, по умолчанию
145
+ `~/.9router/db/data.sqlite`. Файл открывается только на чтение — llmkit его не
146
+ пишет. Строки отчёта — по ключу шлюза (`apiKey`); потребителя различает его
147
+ собственный ключ. Период: `7d`, `12h`, `2w`, `ГГГГ-ММ-ДД` или метка ISO 8601. Нет файла — код 5,
148
+ `GATEWAY_DB_UNAVAILABLE` с путём.
149
+
150
+ ## Python API
151
+
152
+ ```python
153
+ import asyncio
154
+ from rb_llmkit import LlmKit, Task
155
+
156
+ kit = LlmKit(routing=routing) # routing — dict по схеме v1
157
+
158
+
159
+ async def main():
160
+ print(await kit.generate("Одним словом: столица Франции?", system="Отвечай кратко"))
161
+
162
+
163
+ asyncio.run(main())
164
+ ```
165
+
166
+ `LlmKit.ask` возвращает `Answer`: `data`, `model` (запрошенная строка),
167
+ `served_model` (что назвал шлюз), `provider`, `cost_usd`, `attempts`, токены,
168
+ `latency_ms`, `warnings`, `ok`. `ask_many` идёт параллельно (`concurrency`) и не
169
+ рвёт пачку на упавшей задаче; `default` у `Task` — что вернуть, когда моделей нет.
170
+ Синхронные обёртки — `ask_sync`, `generate_sync`, `ask_many_sync`.
171
+
172
+ ## Решения
173
+
174
+ [docs/adr/](docs/adr/). Действующее: ADR-0001 — llmkit надстройка над шлюзом
175
+ 9router, своего состояния и доступа к провайдерам нет.
176
+
177
+ ## Разработка
178
+
179
+ Команды разработки (`uv sync`, гейт `gate check` на этой машине — команда
180
+ `[publish] gate_command` в `.agents/antagor/antagor.toml`)
181
+ и порядок релиза — в [AGENTS.md](AGENTS.md).
182
+
183
+ ```bash
184
+ uv run llm --help # CLI из исходников
185
+ ```
@@ -0,0 +1,168 @@
1
+ # llmkit
2
+
3
+ Надстройка над шлюзом [9router](https://github.com/decolua/9router): вызовы моделей,
4
+ JSON по схеме и пачка задач — через шлюз, без своих клиентов провайдеров.
5
+ Даёт `LlmKit` в Python и команду `llm` для людей и агентов.
6
+
7
+ Своего состояния у llmkit нет: ни базы, ни журнала, ни хранения ключей. Доступ к
8
+ моделям, подписки, квоты и расходы — у шлюза (ADR-0001). Нужен запущенный 9router
9
+ на той же машине.
10
+
11
+ Статус — [CHANGELOG.md](CHANGELOG.md).
12
+
13
+ ## Что это даёт
14
+
15
+ | Возможность | Коротко |
16
+ |---|---|
17
+ | Один вызов модели | `LlmKit.ask` / `generate`; цепочку, фолбэк и повторы исполняет шлюз |
18
+ | JSON по схеме | JSON Schema уходит в шлюз как `response_format`; невалидный ответ повторяется с текстом ошибки |
19
+ | Пачка задач | `ask_many` с ограничением параллельности, падение одной задачи не рвёт пачку |
20
+ | Вся поверхность шлюза | команды `llm image`, `audio`, `video`, `embeddings`, `web`, `model`, `chat` — по одной на семейство эндпоинтов |
21
+ | Расходы | `llm cost` читает журнал шлюза (`usageHistory`) только на чтение, по ключам потребителей |
22
+
23
+ ## Установка
24
+
25
+ Дистрибутив называется **`rb-llmkit`**, импорт — `llmkit`, команда — `llm`.
26
+ Ставить всегда по тегу `vX.Y.Z`.
27
+
28
+ ```bash
29
+ uv add "rb-llmkit @ git+https://github.com/bolandeu/llmkit@vX.Y.Z" # в проект
30
+ uv tool install "rb-llmkit @ git+https://github.com/bolandeu/llmkit@vX.Y.Z" # команда в систему
31
+ ```
32
+
33
+ Репозиторий приватный: на машине нужен доступ к GitHub (`gh auth login` или
34
+ ssh-ключ и адрес `git+ssh://git@github.com/bolandeu/llmkit`). Требуется Python >= 3.11.
35
+
36
+ ## Ключ шлюза и routing
37
+
38
+ Ключ берётся только из окружения; имя переменной называет routing (`key_env`).
39
+ Нет переменной — код 3, `AUTH_MISSING` с её именем.
40
+
41
+ ```bash
42
+ export NINEROUTER_API_KEY=sk-...
43
+ ```
44
+
45
+ Провайдер шлюза и цепочка моделей приходят данными — routing v1 (схема
46
+ `src/rb_llmkit/contracts/routing-v1.schema.json`). Секретов в routing нет.
47
+
48
+ ```json
49
+ {
50
+ "providers": {
51
+ "9router": {"protocol": "openai_compatible", "base_url": "http://localhost:20128/v1",
52
+ "key_env": "NINEROUTER_API_KEY"}
53
+ },
54
+ "chain": ["Deep Sec", "opencode-go"]
55
+ }
56
+ ```
57
+
58
+ - `protocol` — только `openai_compatible` с адресом шлюза.
59
+ - `chain` — имена моделей шлюза строками, как в его настройке (комбо — одна
60
+ строка). Порядок и фолбэк исполняет шлюз: llmkit просит первую.
61
+ - CLI: `--routing '<json>'` или `--routing <файл>`; без него — `LLMKIT_ROUTING_FILE`;
62
+ без него — `routing.json` в каталоге конфигурации (`platformdirs.user_config_dir("llmkit")`,
63
+ macOS — `~/Library/Application Support/llmkit/routing.json`). Нет ничего — код 2,
64
+ `ROUTING_MISSING` с путём по умолчанию.
65
+ - Цепочку можно задать `-m` (повторяемый) в routing без `chain`; оба сразу —
66
+ `ROUTING_INVALID` «chain задана дважды».
67
+
68
+ ## CLI `llm`
69
+
70
+ У всех команд есть `--json` (конверт в stdout), диагностика идёт в stderr.
71
+ Коды выхода: **0** — успех, **1** — непредвиденная ошибка, **2** — неверные
72
+ аргументы или routing, **3** — нет переменной с ключом шлюза, **5** — шлюз
73
+ недоступен, ответил ошибкой или его журнал расходов не читается.
74
+
75
+ ```bash
76
+ llm # справка: список команд, код выхода 0
77
+ llm ask "Столица Франции?" --routing routing.json
78
+ llm ask "Привет" -m "Deep Sec" -m opencode-go # цепочка из CLI, если в routing нет chain
79
+ llm json "Разбери запрос" --schema schema.json # в stdout только JSON-объект
80
+ llm render --template prompt.md --vars vars.json # шаблон mustache; нет переменной — код 2
81
+ llm models --json # провайдеры routing, источник ключа, цепочка
82
+ llm routing validate routing.json # проверка перед сохранением; ROUTING_INVALID с путём к полю
83
+ llm routing import config.toml # перенос config.toml llmkit < 0.8
84
+ llm auth status --check --json # ключ шлюза: откуда и работает ли; 3 — ключ не принят
85
+ llm cost --since 7d --json # расходы из журнала шлюза, по ключам
86
+ llm config show --json # итоговые настройки вызова
87
+ llm doctor --json # готовность: версия, конфиг, routing, шлюз
88
+ llm describe --json # контракт CLI документом OpenCLI
89
+ ```
90
+
91
+ ### Поверхность шлюза
92
+
93
+ Одна команда — один эндпоинт шлюза; ответ типизирован в `--json`, форматы
94
+ провайдера llmkit не разбирает.
95
+
96
+ ```bash
97
+ llm image generate "кот в шляпе" -m openai/gpt-image-1 --out cat.png --json
98
+ llm audio speech "привет" -m openai/gpt-4o-mini-tts --voice alloy --out speech.mp3 --json
99
+ llm audio transcribe speech.mp3 -m openai/whisper-1 --json
100
+ llm audio voices --json
101
+ llm video generate "волна на пляже" -m google/veo-3 --json
102
+ llm video get video_1 --json
103
+ llm embeddings create "текст" -m openai/text-embedding-3-small --json
104
+ llm web search "llmkit" -m perplexity/sonar --json
105
+ llm web fetch https://example.com --json
106
+ llm model list --json
107
+ llm model show deepseek/deepseek-v4.1-flash-1017 --json
108
+ llm chat responses "Столица Франции?" -m openai/gpt-5 --json
109
+ llm chat messages "Столица Франции?" -m anthropic/claude-x --json
110
+ ```
111
+
112
+ Картинка и речь приходят байтами — их место в файле `--out`; ссылку или URL
113
+ `--json` отдаёт в поле `url`.
114
+
115
+ ## Как агент работает с CLI
116
+
117
+ 1. `llm --help` и `llm <команда> --help` — справка из кода: у каждой команды есть
118
+ строка `Example:`, у каждого флага `help=`.
119
+ 2. `--json` — машинный конверт в stdout: `{"ok": true, ...}` или
120
+ `{"ok": false, "error": {"code", "message", "action"}}`.
121
+ 3. Коды выхода говорят, что делать: 0 — готово, 2 — аргументы, 3 — ключ, 5 — шлюз.
122
+ 4. `llm doctor --json` — готовность до работы; `llm describe --json` — контракт
123
+ CLI для каталога инструментов.
124
+
125
+ ## Расходы
126
+
127
+ `llm cost` читает SQLite шлюза: `LLMKIT_GATEWAY_DB`, по умолчанию
128
+ `~/.9router/db/data.sqlite`. Файл открывается только на чтение — llmkit его не
129
+ пишет. Строки отчёта — по ключу шлюза (`apiKey`); потребителя различает его
130
+ собственный ключ. Период: `7d`, `12h`, `2w`, `ГГГГ-ММ-ДД` или метка ISO 8601. Нет файла — код 5,
131
+ `GATEWAY_DB_UNAVAILABLE` с путём.
132
+
133
+ ## Python API
134
+
135
+ ```python
136
+ import asyncio
137
+ from rb_llmkit import LlmKit, Task
138
+
139
+ kit = LlmKit(routing=routing) # routing — dict по схеме v1
140
+
141
+
142
+ async def main():
143
+ print(await kit.generate("Одним словом: столица Франции?", system="Отвечай кратко"))
144
+
145
+
146
+ asyncio.run(main())
147
+ ```
148
+
149
+ `LlmKit.ask` возвращает `Answer`: `data`, `model` (запрошенная строка),
150
+ `served_model` (что назвал шлюз), `provider`, `cost_usd`, `attempts`, токены,
151
+ `latency_ms`, `warnings`, `ok`. `ask_many` идёт параллельно (`concurrency`) и не
152
+ рвёт пачку на упавшей задаче; `default` у `Task` — что вернуть, когда моделей нет.
153
+ Синхронные обёртки — `ask_sync`, `generate_sync`, `ask_many_sync`.
154
+
155
+ ## Решения
156
+
157
+ [docs/adr/](docs/adr/). Действующее: ADR-0001 — llmkit надстройка над шлюзом
158
+ 9router, своего состояния и доступа к провайдерам нет.
159
+
160
+ ## Разработка
161
+
162
+ Команды разработки (`uv sync`, гейт `gate check` на этой машине — команда
163
+ `[publish] gate_command` в `.agents/antagor/antagor.toml`)
164
+ и порядок релиза — в [AGENTS.md](AGENTS.md).
165
+
166
+ ```bash
167
+ uv run llm --help # CLI из исходников
168
+ ```
@@ -0,0 +1,145 @@
1
+ [project]
2
+ name = "rb-llmkit"
3
+ # Версия — из git-тега vX.Y.Z (uv-dynamic-versioning); строку `version =` не добавлять.
4
+ dynamic = ["version"]
5
+ description = "Shared LLM layer: model calls through a gateway with typed answers and spend accounting."
6
+ readme = "README.md"
7
+ license = "MIT"
8
+ license-files = ["LICENSE"]
9
+ authors = [
10
+ { name = "Roman Bolandau" }
11
+ ]
12
+ requires-python = ">=3.11"
13
+ dependencies = [
14
+ "pydantic>=2",
15
+ "platformdirs>=4",
16
+ "typer>=0.27,<0.29",
17
+ "rich>=13",
18
+ "httpx>=0.27",
19
+ # Рендер шаблонов промптов (template.py): точный пин — используются внутренности движка (Ctx, _render).
20
+ "combustache==3.0.1",
21
+ ]
22
+
23
+ [project.scripts]
24
+ llm = "rb_llmkit.cli.main:main"
25
+
26
+ [project.urls]
27
+ Repository = "https://homeserver.tailee01ab.ts.net:3000/bolandeu/llmkit"
28
+
29
+ [build-system]
30
+ requires = ["hatchling", "uv-dynamic-versioning"]
31
+ build-backend = "hatchling.build"
32
+
33
+ [tool.hatch.version]
34
+ source = "uv-dynamic-versioning"
35
+
36
+ [tool.uv-dynamic-versioning]
37
+ vcs = "git"
38
+ style = "pep440"
39
+ fallback-version = "0.0.0"
40
+
41
+ [tool.uv]
42
+ # Пересобирать editable-установку, когда сдвигается коммит или тег: `--version` следует за тегом.
43
+ cache-keys = [{ file = "pyproject.toml" }, { git = { commit = true, tags = true } }]
44
+
45
+ [tool.cli-generator]
46
+ # Где scripts/check_command_docstrings.py (checks Antagor) ищет
47
+ # команды: у llmkit они в src/*/cli/*.py (не commands/), регистрация — `@app.command`.
48
+ commands = "src/*/cli/*.py"
49
+
50
+ # Установка (Standard, Install): инструмент для людей на Mac, ставится и на homeserver.
51
+ [tool.rb.install]
52
+ homeserver = ["rbtools"]
53
+ mac = true
54
+
55
+ [tool.hatch.build.targets.sdist]
56
+ # What a release must not carry: the agent's own files, the forge configs and the dev tooling. The wheel is
57
+ # narrow already (`packages = ["src/<pkg>"]`); this is about the sdist, which is otherwise a copy of the repo.
58
+ exclude = [
59
+ "/.agents",
60
+ "/.claude",
61
+ "/.claude-plugin",
62
+ "/.gitea",
63
+ "/.github",
64
+ "/docs",
65
+ "/scripts",
66
+ "/uv.lock",
67
+ "/AGENTS.md",
68
+ "/CLAUDE.md",
69
+ "/CODING_STANDARDS.md",
70
+ "/CONTEXT.md",
71
+ "/.copier-answers.yml",
72
+ "^\\.gitignore$",
73
+ "/.gitleaks.toml",
74
+ ]
75
+
76
+ [tool.hatch.build.targets.wheel]
77
+ packages = ["src/rb_llmkit"]
78
+
79
+ [tool.hatch.build.targets.wheel.force-include]
80
+ # Установленный CLI читает отсюда [[tool.rb.external]] для `llm describe --json` (opencli.py).
81
+ "pyproject.toml" = "llmkit/_pyproject.toml"
82
+
83
+ [dependency-groups]
84
+ # Мутационное тестирование — периодически и перед крупными релизами, не в гейте:
85
+ # `uv run --group mutation mutmut run`, затем `mutmut results` / `mutmut browse`.
86
+ # Нужен fork(): macOS/Linux. Настройки — [tool.mutmut] ниже.
87
+ mutation = ["mutmut>=3.3"]
88
+ dev = [
89
+ "jsonschema>=4.23",
90
+ "packaging>=24.0",
91
+ "pytest>=8.0",
92
+ "pytest-asyncio>=0.23",
93
+ "pytest-cov>=5.0",
94
+ "pyyaml>=6.0",
95
+ "ruff>=0.6",
96
+ "syrupy>=4.8",
97
+ "ty>=0.0.80",
98
+ ]
99
+
100
+ [tool.pytest.ini_options]
101
+ # Только tests/: mutmut оставляет копию дерева в mutants/.
102
+ testpaths = ["tests"]
103
+ asyncio_mode = "auto"
104
+ addopts = "--cov --cov-report=term-missing:skip-covered"
105
+
106
+ [tool.mutmut]
107
+ source_paths = ["src/rb_llmkit"]
108
+ also_copy = ["scripts/", "pyproject.toml"] # их читают тесты (проверки дистрибутива)
109
+ pytest_add_cli_args = ["--no-cov"] # fail_under убил бы каждого мутанта
110
+ # only_mutate = ["*/db/normalize.py"] # по модулю за раз
111
+
112
+ [tool.coverage.run]
113
+ source = ["src"]
114
+ # Ядро по умолчанию в Python 3.14 растёт по памяти на каждый вызов CLI в тестах.
115
+ core = "ctrace"
116
+
117
+ [tool.coverage.report]
118
+ # Порог — по факту на момент перехода на стандарт; поднимать, не опускать.
119
+ fail_under = 85
120
+ show_missing = true
121
+
122
+ [tool.ty.terminal]
123
+ # Гейт валят только ошибки; ty >= 0.0.84 иначе выходит с 1 и на предупреждениях.
124
+ error-on-warning = false
125
+
126
+ [tool.ruff]
127
+ line-length = 120
128
+
129
+ [tool.ruff.lint]
130
+ select = ["E4", "E7", "E9", "F", "I", "UP", "B", "SIM", "RUF", "S"]
131
+ # Интерфейс и комментарии на русском: кириллица и типографские тире — норма.
132
+ ignore = ["RUF001", "RUF002", "RUF003"]
133
+
134
+ [tool.ruff.lint.isort]
135
+ # `rb_llmkit.*` — свой пакет, даже когда модуль удалён (иначе isort считает его чужим).
136
+ known-first-party = ["llmkit"]
137
+
138
+ [tool.ruff.lint.per-file-ignores]
139
+ "tests/*" = ["S101", "S105", "S106", "S107"]
140
+ # S603/S607: скрипты вызывают git/uv фиксированными списками аргументов, без shell.
141
+ "scripts/*" = ["S101", "S105", "S106", "S603", "S607", "T201"]
142
+
143
+ [tool.ruff.lint.flake8-bugbear]
144
+ # Стиль Typer `param: T = typer.Option(...)` — вызов в значении по умолчанию намеренно.
145
+ extend-immutable-calls = ["typer.Option", "typer.Argument"]
@@ -0,0 +1,72 @@
1
+ """llmkit — общий LLM-слой: вызовы моделей через шлюз 9router, типизированный ответ, учёт расходов.
2
+
3
+ Быстрый импорт: `pydantic` и httpx приходят с первым обращением к `LlmKit`, `Answer`,
4
+ `Routing` и прочим моделям, а не с `import llmkit` (AGENTS.md: меньше 300 мс даже без
5
+ .pyc-кэша). Имена в `__all__` доступны как раньше — через `__getattr__` (PEP 562).
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import importlib
11
+ from typing import Any
12
+
13
+ from .errors import (
14
+ AllModelsFailed,
15
+ ConfigError,
16
+ GatewayUnavailable,
17
+ KeyMissing,
18
+ LlmKitError,
19
+ RoutingInvalid,
20
+ RoutingMissing,
21
+ TemplateError,
22
+ TemplateVariableMissing,
23
+ )
24
+
25
+ # имя в пакете → (модуль, имя в модуле): грузится при первом обращении
26
+ _LAZY: dict[str, tuple[str, str]] = {
27
+ "Answer": ("core", "Answer"),
28
+ "Attempt": ("core", "Attempt"),
29
+ "LlmKit": ("core", "LlmKit"),
30
+ "Stats": ("core", "Stats"),
31
+ "Task": ("core", "Task"),
32
+ "Config": ("config", "Config"),
33
+ "Routing": ("routing", "Routing"),
34
+ "parse_routing": ("routing", "parse"),
35
+ "render": ("template", "render"),
36
+ }
37
+
38
+ __all__ = [
39
+ "AllModelsFailed",
40
+ "Answer",
41
+ "Attempt",
42
+ "Config",
43
+ "ConfigError",
44
+ "GatewayUnavailable",
45
+ "KeyMissing",
46
+ "LlmKit",
47
+ "LlmKitError",
48
+ "Routing",
49
+ "RoutingInvalid",
50
+ "RoutingMissing",
51
+ "Stats",
52
+ "Task",
53
+ "TemplateError",
54
+ "TemplateVariableMissing",
55
+ "parse_routing",
56
+ "render",
57
+ ]
58
+
59
+
60
+ def __getattr__(name: str) -> Any:
61
+ """Ленивая выдача имён из `_LAZY`: модуль грузится при первом обращении."""
62
+ target = _LAZY.get(name)
63
+ if target is None:
64
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
65
+ module, attribute = target
66
+ value = getattr(importlib.import_module(f".{module}", __name__), attribute)
67
+ globals()[name] = value
68
+ return value
69
+
70
+
71
+ def __dir__() -> list[str]:
72
+ return sorted(__all__)
@@ -0,0 +1,21 @@
1
+ """Имена дистрибутива, инструмента и версия шаблона — для `llm describe --json` и тестов.
2
+
3
+ Версия пакета берётся из тега через importlib.metadata; имя дистрибутива записано
4
+ здесь, потому что editable-установка не отображает пакет на дистрибутив.
5
+ """
6
+
7
+ # Имя дистрибутива: [project] name в pyproject.toml (стандарт §10: `rb-<slug>`),
8
+ # отличается от имени импорт-пакета. По нему importlib.metadata находит версию;
9
+ # editable-установку (`uv sync`) по пакету в дистрибутив не отобразить, поэтому
10
+ # имя записано здесь. tests/test_cli.py падает, если оно разойдётся с pyproject.toml.
11
+ DIST_NAME = "rb-llmkit"
12
+ # Прежнее имя дистрибутива на время переименования (стандарт §10): установка под
13
+ # ним (ещё не переустановленная) по-прежнему находит свою версию. Убрать, когда
14
+ # на всех машинах стоит новое имя.
15
+ DIST_NAME_LEGACY: str | None = "llmkit"
16
+ # Имя инструмента (cli-generator architecture.md §12) — каталоги пользователя `llmkit`
17
+ # и префикс переменных `LLMKIT_`. Записано, а не выводится из имени CLI (`llm`).
18
+ TOOL = "llmkit"
19
+ # Релиз cli-generator, с которым сверен перенесённый вручную код (describe;
20
+ # AGENTS.md) — для `llm describe --json`. copier у llmkit нет.
21
+ TEMPLATE_VERSION: str | None = "v1.5.6"
@@ -0,0 +1,24 @@
1
+ """Запуск корутины из синхронного кода.
2
+
3
+ Если в этом потоке уже крутится event loop (Jupyter, обработчик внутри
4
+ асинхронного кода), `asyncio.run` бросает RuntimeError — тогда корутина
5
+ выполняется в отдельном потоке со своим loop.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import asyncio
11
+ from collections.abc import Coroutine
12
+ from concurrent.futures import ThreadPoolExecutor
13
+ from typing import Any, TypeVar, cast
14
+
15
+ T = TypeVar("T")
16
+
17
+
18
+ def run(coro: Coroutine[Any, Any, T]) -> T:
19
+ try:
20
+ asyncio.get_running_loop()
21
+ except RuntimeError:
22
+ return asyncio.run(coro)
23
+ with ThreadPoolExecutor(max_workers=1) as pool:
24
+ return cast(T, pool.submit(asyncio.run, coro).result())