Skip to content

Plugin authoring

Developer guide for building plugins on the Threadory platform — Connectors, Skills, and Domain Packs.

This directory documents the three plugin contracts exposed by the kernel and walks through how to build each one against the real connector_base, skill_base, and pack_base packages in this repository.

Table of contents

  1. Overview — the 5-layer architecture, plugin types, manifests, kernel purity rule
  2. Authoring a Connector — SourceConnector + ActionConnector Protocols, manifest, auth methods, webhook + OAuth helpers
  3. Authoring a Skill — Skill Protocol, SkillManifest, triggers, @skill decorator, SkillContext sub-APIs, stateful vs stateless patterns
  4. Authoring a Domain Pack — DomainPack and its 4 sub-Protocols, applies_to filter, inheritance via extends, glossary loader
  5. Testing — pytest layout, Postgres testcontainers pattern, KernelMock, FakeLLMRouter, golden datasets
  6. Publishing — local install, entry-point registration, version compatibility

Quick map

Plugin type Base package Entry-point group Manifest section name
Connector connector_base knowledge_os.connectors connector:
Skill skill_base knowledge_os.skills skill:
Domain Pack pack_base knowledge_os.domain_packs domain_pack:

Common pattern

Every plugin is a self-contained Python package shaped as:

packages/<your_plugin>/
├── pyproject.toml           # declares the entry-point group + name
├── src/<your_plugin>/
│   ├── __init__.py
│   ├── manifest.yaml        # validated by pydantic at import time
│   └── <implementation>.py
└── tests/
    └── test_<plugin>.py     # unit + contract tests
  1. Ship a manifest.yaml next to the implementation module — pydantic v2 validates it on load (extra="forbid", frozen=True on every model).
  2. Register your class via Python entry points in pyproject.toml.
  3. Cover the implementation with pytest-asyncio (asyncio_mode = "auto") and the helpers from testing_kit (KernelMock, FakeLLMRouter, golden file helpers).

Authoritative source

The canonical contract spec lives in doc-platform-rewrite/02_plugin_contracts.md in the repository. This guide is the developer-facing companion: shorter, with code recipes, kept in sync with the in-tree connector_base, skill_base, pack_base source. When the two disagree, the spec wins; please open an issue.

Prerequisites

  • Python 3.12
  • uv 0.4+
  • Familiarity with pydantic v2, async Python, and JSON Schema draft-2020-12
  • A checkout of this monorepo (the plugin base packages are workspace members)