docs: per-module README + root navigation hub + CI/release workflows

- README.md в каждом подмодуле: для библиотек — описание проблемы, подключение через maven-central/caffeine, версии в gradle/libs.versions.toml. Для запускаемых модулей — команды запуска + переменные среды с дефолтами. - Корневой README.md переписан как навигационный хаб: что это, где клиенты, где серверы, как собрать, как опубликовать. - build.gradle.kts: per-module POM-description через единую карту в rootProject.extra (порядок важен — нужно ДО apply плагина KMP, поэтому beforeEvaluate в subprojects). - .gitea/workflows/ci.yml (новый): build + jvmTest + shadowJar на PR/push main. - .gitea/workflows/release.yml (обновлён): публикует библиотеки в caffeine Nexus + собирает 3 fatjar'а и крепит их к release как бинарные ассеты.
2026-09-16 16:24:03 +03:00
parent e68db11aaa
commit 0fdc12695e
18 changed files with 1279 additions and 364 deletions
@@ -0,0 +1,73 @@
+# :agent-toolsets — `pw.binom.agentik.toolsets`
+
+**Ядро механики toolsets: `ToolsetRegistry`, `ToolsetDispatchPolicy`,
+встроенные тулы `enable_toolset` / `disable_toolset`, `SyncLiteTool` базовый
+класс.**
+KMP, не зависит от `:standalone`, переиспользуем в Android и в любом другом
+LiteTool-агенте.
+
+## Какую проблему решает
+
+В проде у агента может быть **сотня** инструментов (MCP-серверы, кастомные
+тулы, встроенные операции). Слать их все в каждый LLM-запрос:
+
+1. **Раздувает контекст** — описание тула ~50–200 токенов × 100 тулов = 20K токенов
+   в system prompt без пользы.
+2. **Увеличивает latency** — модель тратит время на выбор из длинного списка.
+3. **Снижает качество** — модель путается между похожими названиями.
+
+Toolsets группируют тулы **по домену** (`filesystem`, `network`, `devops`, …).
+Активированы только 2-3 одновременно. `enable_toolset("filesystem")` —
+включает целую группу одним обращением; тулы появляются в system prompt +
+регистрируются как вызываемые. `disable_toolset(...)` — убирает.
+
+## Архитектура
+
+```kotlin
+interface Toolset {
+    val name: String                                              // "filesystem"
+    val title: String                                             // "File operations"
+    val enabled: Boolean                                          // текущее состояние
+    suspend fun enabledTools(context: ToolsetContext): List<LiteTool>
+    suspend fun systemPromptSection(context: ToolsetContext): String
+}
+
+class ToolsetRegistry {
+    fun register(toolset: Toolset)
+    fun list(): List<Toolset>
+    suspend fun enable(name: String): Boolean
+    suspend fun disable(name: String): Boolean
+}
+
+class ToolsetDispatchPolicy {
+    fun buildDispatch(): DispatchPolicy                            // подаётся в LiteLlm
+}
+```
+
+Встроенные тулы — `EnableToolsetTool` / `DisableToolsetTool` /
+`SystemPromptToolsetSection` — дают LLM самой управлять составом инструментов.
+База для кастомных тулов — `SyncLiteTool` (обёртка над `LiteTool`,
+синхронная `execute(args): String`).
+
+## Подключение
+
+```kotlin
+commonMain {
+    implementation("pw.binom.agentik:agent-toolsets:$version")
+    // Транзитивно: :storage-core (для ToolsetContext) + :proto
+}
+```
+
+## Где смотреть версии
+
+- `version` из `gradle.properties` (`version=0.1.0`)
+- релизы: `https://git.binom.pw/subochev/agentik/releases`
+
+## Сборка
+
+```bash
+./gradlew :agent-toolsets:build
+```
+
+KMP-таргеты — полный набор. Зависимости — `:storage-core` + `:proto` +
+`kotlinx-coroutines` + `kotlinx-serialization`.