Metadata-Version: 2.4
Name: arkady-plugin
Version: 0.10.3
Summary: Arkady Plugin SDK
Keywords: arkady,plugin,sdk
Author: reraaaaa
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Dist: flask>=3.1.3
Requires-Dist: werkzeug>=3.1.8
Requires-Dist: gevent>=26.4.0
Requires-Dist: h11>=0.16.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic-settings>=2.14.2
Requires-Dist: pydantic>=2.13.4
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: requests>=2.33.1
Requires-Dist: socksio>=1.0.0
Requires-Dist: tiktoken>=0.12.0
Requires-Dist: yarl>=1.23.0
Requires-Dist: packaging>=26.2
Requires-Python: >=3.12
Project-URL: source, https://github.com/reraaaaa/arkady-plugin-sdk
Project-URL: homepage, https://github.com/reraaaaa/arkady-plugin-sdk
Project-URL: issues, https://github.com/reraaaaa/arkady-plugin-sdk/issues
Description-Content-Type: text/markdown

# Arkady Plugin SDK

Python SDK для разработки плагинов Arkady.

## Разработка

Репозиторий использует [`just`](https://github.com/casey/just) как командный раннер.
Установить можно любым удобным пакетным менеджером или через uv:

```bash
uv tool install rust-just
```

Основные команды разработки:

```bash
just dev       # Синхронизировать дефолтные dev-зависимости
just fmt       # Применить автоформатирование
just lint      # Форматирование + автофиксы линта
just check     # Проверить lockfile, форматирование и линт
just test      # Запустить тесты SDK
just build     # Собрать source- и wheel-дистрибутивы
just docs      # Сгенерировать документацию по схемам
```

## Поддержка polling-режима для LLM

SDK 0.9.0 добавляет поддержку вызова LLM через polling. Теперь модель может
объявить фичу `polling` и реализовать методы опроса — плагины могут отправлять
долгоживущие задания провайдеру и позже проверять статус через короткий
цикл запрос/ответ.

Результаты polling бывают трёх состояний:

- `running` — возвращает состояние, которым владеет плагин, для следующей проверки.
- `succeeded` — возвращает финальный результат LLM.
- `failed` — возвращает терминальную ошибку.

## Управление версиями

SDK следует Semantic Versioning (a.b.c):

- a: мажорная версия — значимые архитектурные изменения или несовместимые правки API
- b: минорная версия — добавление новых фич с сохранением обратной совместимости
- c: патч-версия — обратно совместимые исправления багов

### Для пользователей SDK

При объявлении зависимости от этого SDK рекомендуется указывать ограничения версии так, чтобы:

- разрешать патч- и минорные обновления (баг-фиксы и новые фичи)
- запрещать мажорные обновления во избежание breaking changes

Пример в зависимостях вашего проекта:

```python
arkady_plugin >= 0.8
```

## Справочник по версиям манифеста

Для спецификации манифеста введены два поля версионирования:

- `meta.version` — версия спецификации манифеста, для обратной совместимости. При установке старого плагина в новую версию Arkady сложно гарантировать отсутствие breaking changes, но по этому полю Arkady может их обнаружить. Если версия не поддерживается — Arkady использует только поддерживаемую часть функционала плагина.
- `meta.minimum_arkady_version` — минимальная версия Arkady, для прямой совместимости. При установке нового плагина в старую версию Arkady многие новые фичи могут быть недоступны, но указание минимальной версии Arkady подсказывает пользователю, до какой версии нужно обновиться.

### Справочник Meta.Version

| Версия манифеста | Описание                                                                                                                                                                                                                   |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0.0.2            | Поскольку `ToolProviderType` теперь поддерживает `mcp`, старая реализация ломается при выборе пользователем `mcp`-инструмента в Arkady — версия поднята до 0.0.2, чтобы Arkady знал: `mcp` отключён при meta.version ниже 0.0.2. |
| 0.0.1            | Первый релиз                                                                                                                                                                                                               |

### Справочник Meta.MinimumArkadyVersion

| Минимальная версия Arkady | Версия SDK    | Описание                                        |
| -------------------- | ------------- | -------------------------------------------------- |
| 1.2.0                | 0.2.0         | Поддержка получения информации о приложении                  |
| 1.4.0                | 0.0.1-beta.49 | Поддержка мультимодального вывода LLM                      |
| 1.4.0                | 0.3.1         | Поддержка OAuth для плагинов            |
| 1.5.1                | 0.4.0         | Поддержка типа параметра `dynamic-select`            |
| 1.5.1                | 0.4.0         | Поддержка structured output для LLM                      |
| 1.6.0                | 0.4.1         | Поддержка поля `dark-icon` в манифесте              |
| 1.7.0                | 0.4.2         | Поддержка OAuth для плагинов            |
| 1.8.1                | 0.4.4         | Поддержка filename в MultiModalPromptMessageContent |
| 1.9.0                | 0.5.0         | Поддержка функционала Datasource для плагинов       |
| 1.10.0               | 0.6.0         | Поддержка функционала Trigger для плагинов       |
| 1.11.0               | 0.7.0         | Поддержка мультимодального Reranking / Embeddings          |
| 1.14.0               | 0.8.1         | Чистка зависимостей и структуры проекта           |
| 1.14.2               | 0.9.0         | Поддержка polling-вызовов LLM-плагинов       |

---
English version: [README.en.md](README.en.md)
