blondie-types 0.1.0

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). The release flow is automated:

# 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