piilot-sdk

Public SDK for building Piilot plugins — the AI cockpit with data sovereignty.

What is it

piilot-sdk is the stable, narrow public contract Piilot plugins import from. A plugin MUST only import from piilot.sdk.* — any import from backend.* is refused at boot by the loader's AST check.

The SDK exposes primitives for:

• Connectors — credentials storage with manifest-driven auto-encrypt
• Tools — agent tool registration with namespace isolation
• Modules — dashboards and workflow surfaces (register_module)
• Agents — session scope + templates (register_template) + system prompt builders
• HTTP — register_router / register_webhook_router with auth deps
• DB — RLS-aware cursor, run_in_thread, execute_values, Json
• Scheduler — register_sync_handler for per-provider sync dispatch
• Cache — async Redis primitives with namespace auto-prefix
• Storage — async S3 primitives with namespace auto-prefix
• Access — check_grant passthrough
• Crypto — mask_api_key helper

Install

pip install piilot-sdk

Quick start

Create a plugin entry point:

# piilot_pack_hello/__init__.py
from piilot.sdk import Plugin, Context
from piilot.sdk import tools, http

class Plugin(Plugin):
    def register(self, ctx: Context) -> None:
        tools.register_tool({
            "id": "hello.greet",
            "label_key": "hello.tools.greet.label",
            "description_key": "hello.tools.greet.description",
            "callable": lambda name: f"Hello, {name}!",
        })

        http.register_router(
            routes=[...],
            prefix="/api/hello",
        )

Declare it as a Piilot plugin in your pyproject.toml:

[project.entry-points."piilot.plugins"]
hello = "piilot_pack_hello:Plugin"

[tool.piilot.plugin]
manifest_version = 1
namespace = "hello"
sdk_compat = ">=0.7.0,<1.0.0"
# ...

Documentation

Full guide: PLUGIN_DEVELOPMENT.md.

Changelog: SDK_CHANGELOG.md.

Template repo: piilot-plugin-template.

Versioning

Semver. Breaking changes bump the major. Plugins pin a compatible range via sdk_compat in their manifest.

License

Apache-2.0. See LICENSE.