Metadata-Version: 2.4
Name: blondie-types
Version: 0.1.1
Summary: Public SDK types for authoring Blondie plugins (backlog backends, CI providers, LLM tools).
Project-URL: Homepage, https://github.com/iva2k/blondie
Project-URL: Documentation, https://github.com/iva2k/blondie/blob/main/docs/PLUGINS.md
Project-URL: Repository, https://github.com/iva2k/blondie
Project-URL: Issues, https://github.com/iva2k/blondie/issues
Author-email: iva2k <iva2k@yahoo.com>
Maintainer-email: iva2k <iva2k@yahoo.com>
License: MIT License
        
        Copyright (c) 2026 Ilya I
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agent,blondie,llm,plugins,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: pydantic>=2.8.0
Requires-Dist: typing-extensions>=4.10.0
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# blondie-types

Public SDK types for authoring [Blondie](https://github.com/iva2k/blondie)
plugins. Plugins import every Blondie type they need from this single
package.

* **Distribution name** (PyPI): `blondie-types`
* **Import name**: `blondie`
* **Contents**: ABCs, dataclasses, enums, error classes, capability
  constants, and API protocols. No runtime code.
* **Dependencies**: stdlib + `pydantic` + `typing_extensions`.

The Blondie runtime depends on `blondie-types`; `blondie-types` does not
depend on the runtime. Plugins develop, test, and ship outside the
Blondie repo with `blondie-types` as their only Blondie-side dependency.

## Quick start

```bash
pip install blondie-types
```

```python
from blondie import (
    BacklogBackend,
    BackendProvider,
    Plugin,
    PluginTool,
    Task,
    TaskStatus,
    ToolProvider,
)


class MyTool(PluginTool):
    name = "my_tool"
    description = "A tiny example."

    async def execute(self, **kwargs) -> str:
        self.api.journal.info("hello from my_tool")
        return "ok"


class MyPlugin(Plugin):
    def provides(self):
        return [ToolProvider(MyTool)]
```

## Top-level exports

| Symbol                      | Kind      | Module             |
|:----------------------------|:----------|:-------------------|
| `Plugin`                    | ABC       | `blondie.plugins`  |
| `Provider`                  | ABC       | `blondie.plugins`  |
| `BackendProvider`           | dataclass | `blondie.plugins`  |
| `CIProviderProvider`        | dataclass | `blondie.plugins`  |
| `ToolProvider`              | dataclass | `blondie.plugins`  |
| `RegistrationContext`       | dataclass | `blondie.plugins`  |
| `PluginInfo`                | dataclass | `blondie.plugins`  |
| `PluginEvent`               | dataclass | `blondie.plugins`  |
| `PLUGIN_API_VERSION`        | int       | `blondie.plugins`  |
| `PluginTool`                | ABC       | `blondie.tools`    |
| `ToolAPI`                   | Protocol  | `blondie.tools`    |
| `BacklogBackend`            | ABC       | `blondie.backlog`  |
| `BackendAPI`                | Protocol  | `blondie.backlog`  |
| `Task`, `Sprint`, `Comment` | dataclass | `blondie.backlog`  |
| `Priority`, `TaskStatus`    | enum      | `blondie.backlog`  |
| `TaskFormatter`             | ABC       | `blondie.backlog`  |
| `CredentialSpec`            | dataclass | `blondie.backlog`  |
| `BackendError` (+ family)   | exception | `blondie.backlog`  |
| `CAP_*`                     | constants | `blondie.backlog`  |
| `CIProvider`                | ABC       | `blondie.ci`       |
| `CIAPI`                     | Protocol  | `blondie.ci`       |
| `Journal`                   | Protocol  | `blondie.journal`  |

The flat `from blondie import X` form is preferred; per-area submodules
are also exposed for selective import.

## Versioning

The SDK follows [Semantic Versioning](https://semver.org/). Two version
numbers travel together:

* The **distribution version** in `pyproject.toml` (visible as
  `blondie.__version__`, sourced from package metadata) — bumped on every
  release.
* The **plugin contract version** `blondie.PLUGIN_API_VERSION` — bumped
  on every breaking change to the public surface re-exported from
  `blondie`.

Release notes live in [CHANGELOG.md](CHANGELOG.md) (Keep-a-Changelog
format). The release flow is automated:

```bash
# 1. Land your changes; describe them under '## [Unreleased]' in CHANGELOG.md.
# 2. From the repo root, run one of:
poe bump-types --patch          # bug fixes
poe bump-types --minor          # additive change
poe bump-types --major          # breaking change (also bump PLUGIN_API_VERSION)
poe bump-types --to 1.2.3       # explicit target

# 3. The script edits pyproject.toml and CHANGELOG.md. Review:
git diff packages/blondie-types/

# 4. Commit, tag, push:
git commit -am "[#NNN] blondie-types vX.Y.Z"
git tag blondie-types-vX.Y.Z
git push && git push origin blondie-types-vX.Y.Z
```

The tag triggers `.github/workflows/blondie-types-publish.yml`, which
publishes to PyPI via OIDC trusted publishing and creates a matching
GitHub Release with the CHANGELOG section as release notes and the
sdist + wheel attached as assets.

## License

MIT
