blondie-types 0.1.2

Public SDK types for authoring Blondie plugins (backlog backends, CI providers, LLM tools).

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
• 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 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. 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 - Keep a Changelog format.

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