Metadata-Version: 2.4
Name: arkady-plugin
Version: 0.10.2
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

A Python SDK for building Arkady plugins.

## Development

This repository uses [`just`](https://github.com/casey/just) as its command runner.
Install it with your preferred package manager, or with uv:

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

Common development commands:

```bash
just dev       # Sync default dev dependencies
just fmt       # Apply formatting fixes
just lint      # Format and apply lint fixes
just check     # Check lockfile, formatting, and linting
just test      # Run SDK tests
just build     # Build source and wheel distributions
just docs      # Generate schema documentation
```

## LLM Polling Support

SDK 0.9.0 adds support for polling-based LLM invocation. A model can now
declare the `polling` feature and implement polling methods, allowing plugins
to submit long-running provider jobs and return later checks through a short
request/response flow.

Polling results use three states:

- `running` returns plugin-owned state for the next check.
- `succeeded` returns the final LLM result.
- `failed` returns a terminal error.

## Version Management

This SDK follows Semantic Versioning (a.b.c):

- a: Major version - Indicates significant architectural changes or incompatible API modifications
- b: Minor version - Indicates new feature additions while maintaining backward compatibility
- c: Patch version - Indicates backward-compatible bug fixes

### For SDK Users

When depending on this SDK, it's recommended to specify version constraints that:

- Allow patch and minor updates for bug fixes and new features
- Prevent major version updates to avoid breaking changes

Example in your project's dependency management:

```python
arkady_plugin >= 0.8
```

## Manifest Version Reference

For the manifest specification, we've introduced two versioning fields:

- `meta.version` - The version of the manifest specification, designed for backward compatibility. When installing an older plugin to a newer Arkady, it's difficult to ensure breaking changes never occur, but at least Arkady can detect them through this field. Once an unsupported version is detected, Arkady will only use the supported parts of the plugin.
- `meta.minimum_arkady_version` - The minimum version of Arkady, designed for forward compatibility. When installing a newer plugin to an older Arkady, many new features may not be available, but showing the minimum Arkady version helps users understand how to upgrade.

### Meta.Version Reference

| Manifest Version | Description                                                                                                                                                                                                                   |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0.0.2            | As `ToolProviderType` now supports `mcp`, an elder implementation is going to broken when user selected a `mcp` tool in Arkady, so we bump it to 0.0.2 to ensure Arkady knows that `mcp` is disabled if meta.version under 0.0.2. |
| 0.0.1            | Initial release                                                                                                                                                                                                               |

### Meta.MinimumArkadyVersion Reference

| Minimum Arkady Version | SDK Version   | Description                                        |
| -------------------- | ------------- | -------------------------------------------------- |
| 1.2.0                | 0.2.0         | Support fetching application info                  |
| 1.4.0                | 0.0.1-beta.49 | Support LLM multimodal output                      |
| 1.4.0                | 0.3.1         | Support OAuth functionality for plugins            |
| 1.5.1                | 0.4.0         | Support `dynamic-select` parameter type            |
| 1.5.1                | 0.4.0         | Support LLM structured output                      |
| 1.6.0                | 0.4.1         | Support `dark-icon` field in manifest              |
| 1.7.0                | 0.4.2         | Support OAuth functionality for plugins            |
| 1.8.1                | 0.4.4         | Support filename in MultiModalPromptMessageContent |
| 1.9.0                | 0.5.0         | Support Datasource functionality for plugins       |
| 1.10.0               | 0.6.0         | Support Trigger functionality for plugins          |
| 1.11.0               | 0.7.0         | Support Multimodal Reranking / Embeddings          |
| 1.14.0               | 0.8.1         | Dependency and project structure cleanup           |
| 1.14.2               | 0.9.0         | Support polling-based LLM plugin invocations       |
