Metadata-Version: 2.4
Name: blondie-types
Version: 0.1.2
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](https://keepachangelog.com/en/1.1.0/) format.

### Cutting a release

One command runs the full pipeline. Add your release notes under
`## [Unreleased]` in [CHANGELOG.md](CHANGELOG.md), commit them, then from the repo root:

```bash
poe release-types               # interactive: auto-detect bump, prompt to confirm
poe release-types patch         # explicit kind
poe release-types minor
poe release-types major
poe release-types 1.2.3         # explicit target version
poe release-types --dry-run     # plan only; no mutations
poe release-types --no-push     # stop after tagging; push later
poe release-types patch --yes   # non-interactive, accept default
poe release-types --task 704 minor
```

`release-types` runs cautious pre-flight checks (working tree clean,
branch tracks remote, lint/typecheck/tests/build pass, CHANGELOG ↔
pyproject agreement, `[Unreleased]` non-empty), then auto-detects the
bump kind from the `[Unreleased]` section and conventional commits since
the last tag (heuristics: `### Added` → minor, `### Changed` /
`### Removed` / `BREAKING` → major, `### Fixed` → patch; `feat!:` →
major, `feat:` → minor, `fix:` → patch). The default is presented in an
interactive prompt with the reasons it was picked.

Each subsequent step is **idempotent** — re-running after Ctrl-C resumes
from the first incomplete step. The pipeline:

1. **Bump** — pyproject.toml + CHANGELOG.md (`scripts/bump_blondie_types_version.py`).
2. **Commit** — `[#NNN] blondie-types vX.Y.Z` (or override with `--message`).
3. **Tag** — `blondie-types-vX.Y.Z` (annotated).
4. **Push** — branch + tag.

Pushing 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.

### Lower-level tasks

For step-at-a-time control or manual recovery:

```bash
poe verify-types-release        # check pyproject ↔ CHANGELOG agreement
poe bump-types --patch          # bump pyproject + promote [Unreleased]
poe bump-types --to 1.2.3
poe build-types                 # build sdist + wheel under packages/blondie-types/dist/
poe test-types                  # run the SDK pytest suite
```

## License

MIT
