blondie-types

Public SDK types for authoring Blondie plugins. Plugins import every Blondie type they need from this single package.

• Distribution name (PyPI): blondie-types
• Import name: blondie_types
• 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

pip install blondie-types

from blondie_types 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

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

Versioning

The SDK follows Semantic Versioning. Two version numbers travel together:

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

Changelog conventions

Release notes live in CHANGELOG.md and follow Keep a Changelog with one local adjustment: when a release uses sub-section groupings (Added, Changed, Fixed, Removed, Security, Deprecated), prefix each sub-heading with the release version - e.g. ### 0.1.2 Added rather than the plain ### Added. The plain headings repeat verbatim across releases, which collides with markdownlint's MD024 (no-duplicate-heading) and breaks Markdown anchor links to a specific release's section. Versioned sub-headings stay unique, anchors resolve, and the Keep-a-Changelog grouping is preserved.

While editing notes under ## [Unreleased] the next version isn't known yet, so authors write the placeholder Unreleased in place of the version, e.g.:

## [Unreleased]

### Unreleased Added

- new feature alpha

### Unreleased Fixed

- bug X

scripts/bump_blondie_types_version.py rewrites every ### Unreleased <Group> to ### <new_version> <Group> when promoting the section, mirroring how it rewrites the parent ## [Unreleased] heading itself. Flat bullet lists directly under the version heading are also acceptable when no grouping is needed; the scripts/release_blondie_types.py auto-detection looks for both styles.

Cutting a release

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

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:

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