SDK overview
The Imperal SDK — federal extension contract, manifest schema v3, typed Pydantic params, runtime quality guarantees
The Imperal SDK is how you build extensions for Webbee 🐝 in Python. It enforces the federal extension contract (manifest schema v3, 11 ERROR-severity validators V14–V22 + V24 + V31) and ships runtime quality guarantees — the Pydantic feedback loop, declarative center-overlay surfaces, federal-grade panel rendering contracts, and per-user encrypted secrets backed by the platform KMS (@ext.secret + ctx.secrets, v4.2.2+).
For per-release migration notes, see the changelog.
Install
pip install --upgrade imperal-sdkFederal hygiene
Bump every venv that imports imperal_sdk in the same window. Worker fleets that mix old and new SDK lines work but are not recommended — pin the version in your pyproject.toml and roll all workers together.
Verify
python -c "import imperal_sdk; print(imperal_sdk.__version__)"Hello world
from imperal_sdk import Extension, ChatExtension, ActionResult
from pydantic import BaseModel, Field
ext = Extension(
"hello-world",
display_name="Hello World",
description="Minimal demonstration extension for Webbee.",
icon="icon.svg",
actions_explicit=True,
)
chat = ChatExtension(ext, tool_name="hello-world", description="Hello World assistant")
class GreetParams(BaseModel):
name: str = Field(description="Person to greet")
@chat.function(
description="Send a friendly greeting by name.",
action_type="read",
)
async def greet(ctx, params: GreetParams):
return ActionResult.success({"text": f"Hello, {params.name}!"}, summary="Greeting sent")That's a real, complete, federal-clean extension. The LLM sees the JSON schema for GreetParams and calls greet(name="Alex") when a user types "say hi to Alex".
Reference contents
Complete API surface
Every SDK element in one place — decorators, ctx, manifest, validators.
Manifest reference
Every field in imperal.json — what it does, what's required, what it accepts.
Decorators reference
@chat.function, @ext.skeleton, @ext.schedule, @ext.panel — full API.
Validators reference
V14-V22 + V24 + V31 — what each validator catches and how to fix common failures.
Pydantic feedback loop
The runtime retry layer + 5 federal invariants protecting it.
Changelog
Release notes for every v4.x version with migration notes.
Compatibility
| Surface | Supported |
|---|---|
| Python | 3.11+ |
| Anthropic models | claude-haiku-4-5, claude-sonnet-4-6, claude-opus-4-7 |
| OpenAI models | gpt-4.1 family, gpt-5 family, o3, o-series |
| Local models via BYOLLM | Ollama-compatible servers (Qwen, Llama, etc.) |
| Pydantic | v2.x |
| ICNLI Worker | 1.30+ |