Imperal SDK overview
The Imperal SDK — build federal-grade Python extensions for Webbee: manifest schema v3, typed Pydantic params, runtime quality guarantees & federal validators.
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), the SDL Typed Return Contract (every @chat.function returns a typed sdl.Entity / sdl.EntityList[T] via data_model=), 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, sdl
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 Greeting(sdl.Entity, sdl.Bodied):
pass
class GreetParams(BaseModel):
name: str = Field(description="Person to greet")
@chat.function(
"greet",
description="Send a friendly greeting by name.",
action_type="read",
data_model=Greeting, # ← read tools declare their SDL return shape (V23)
)
async def greet(ctx, params: GreetParams) -> ActionResult:
return ActionResult.success(
Greeting(id=params.name, title=f"Hello, {params.name}!", body=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"); the handler returns a typed SDL Greeting entity — the now-required data_model= return shape for every @chat.function.
Every handler MUST be annotated -> ActionResult (validator V5).
Reference contents
SDL reference
The Structured Data Layer — sdl.Entity, sdl.EntityList[T], facets and roles for every data_model= return shape.
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-8 |
| 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+ |
Where to next
Performance
Performance for Webbee extensions: latency budgets, caching, batching, skeleton and panel patterns, and avoiding slow blocking calls so handlers feel fast.
Element Catalog
Browse every element of the Imperal SDK in one place — UI components, decorators, SDL roles & functions, ctx methods and data types, grouped by category and live-filterable.