kollabor-plugins

kollabor-plugins is the plugin framework for Kollabor.

It provides plugin discovery, safe instantiation, lifecycle management, status collection, the base plugin class, and SDK helpers. Concrete plugins live in the repo-level plugins/ directory or installed package plugin locations.

Current Role

Discover plugin classes from development and installed plugin directories.
Instantiate plugins with shared dependencies such as event bus, config, and services.
Provide a stable BasePlugin lifecycle for initialization, hook registration, status, config widgets, and shutdown.
Collect plugin startup/status information without crashing the host app.
Provide utility helpers for safe optional-method calls.

Architecture

Module	Responsibility
`base.py`	`BasePlugin` lifecycle and default methods
`discovery.py`	plugin class discovery
`factory.py`	dependency-aware plugin construction
`registry.py`	plugin registration and lifecycle registry
`collector.py`	status/startup info collection
`plugin_sdk.py`	helper API for plugin authors
`plugin_utils.py`	safe calls, metadata, interface validation

Plugin Shape

from kollabor_plugins import BasePlugin


class MyPlugin(BasePlugin):
    name = "my_plugin"
    version = "1.0.0"
    description = "Adds one useful thing"

    async def initialize(self, args=None, **kwargs):
        return None

    async def register_hooks(self):
        return None

    async def shutdown(self):
        return None

Discovery order:

./plugins/
Installed package plugin locations.

Lifecycle:

Discover plugin classes.
Instantiate with dependencies.
Call initialize().
Call register_hooks().
Call shutdown() on app exit.

Known Gaps

Plugin metadata and config schemas are partly convention-based; stronger typed metadata would help UI and docs generation.
Discovery order and dependency injection behavior should be covered by more integration tests across local and installed plugin layouts.
Plugin shutdown must remain best-effort and non-blocking; long-running plugin tasks need clearer ownership and cancellation guidance.

Roadmap

Phase 1: Authoring clarity

Add a plugin author guide generated from real BasePlugin methods.
Document config widget and status-line conventions.
Add examples for hook-only, command, fullscreen, and background-task plugins.

Phase 2: Lifecycle hardening

Add tests for plugin discovery, instantiation failures, and shutdown failures.
Track plugin-owned tasks/resources explicitly.
Make startup/status collection easier to inspect from CLI and engine surfaces.

Phase 3: Packaging and marketplace readiness

Normalize plugin metadata fields for installed packages.
Document compatibility/version expectations for plugins.
Prepare a stable manifest format if plugins move toward external distribution.

Development

Targeted validation examples:

python -m py_compile packages/kollabor-plugins/src/kollabor_plugins/*.py
python -m pytest tests/unit/commands/test_all_command_handlers.py -q

Dependencies

kollabor-events

License

MIT

Metadata

Release files for kollabor-plugins 0.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kollabor-plugins 0.8.0
File	Size	Uploaded
kollabor_plugins-0.8.0.tar.gz	18.6 kB	Sep 18, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for kollabor-plugins 0.8.0
File	Interpreter	ABI	Platform	Reset
kollabor_plugins-0.8.0-py3-none-any.whl 21.4 kB Sep 18, 2026	Python 3	none	any	Details

Total release size: 40.0 kB

Release files / kollabor_plugins-0.8.0.tar.gz

Download URL	kollabor_plugins-0.8.0.tar.gz
Size	18.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`01acbebab2a561d05c61537f3d542833e7da7c1f942bdc1cb38e2f8e7e884f48`
BLAKE2b-256 checksum How to use checksums	`4ea070559142e15904dff3e681c9a44d570fc0b97fb48aea76622bbceb9cef88`
Upload date	Sep 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.14`

Release files / kollabor_plugins-0.8.0-py3-none-any.whl

Download URL	kollabor_plugins-0.8.0-py3-none-any.whl
Size	21.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`d8efdfe1ab9494afec0b2e93b0181f8df7de4270bfcc8237c51dd54ecd711123`
BLAKE2b-256 checksum How to use checksums	`781fed67121b0338b1b4ff31fc96656cb4a26aa34748d1f0a3f36639526359d5`
Upload date	Sep 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.14`