Imperal SDK
The SDK for Webbee 🐝 — agent of Imperal Cloud, the world's first AI Cloud OS.
Build extensions in Python. Webbee picks them up. Users install them. You get paid.
What is this?
Imperal Cloud is the world's first AI Cloud Operating System. Webbee 🐝 is its agent — Web 3.0-native, cloud-modular, persistent across surfaces. First of its kind. There is no precedent.
Users live in natural language. Webbee runs the rest:
"send the Q3 report to Sarah" — Webbee sends it.
"what was our biggest customer last month?" — Webbee answers from your real data.
"book me a flight to Berlin Friday morning, cheapest under $400, aisle" — Webbee books it across mail, calendar, payment, and travel APIs in one move.
It works because of three things: the agent (Webbee), the kernel (the OS layer that orchestrates intent, action, audit, and recovery), and extensions — Python packages that hand Webbee new superpowers.
This SDK is how you build extensions.
pip install imperal-sdk
5-minute quickstart
Scaffold
mkdir hello-world && cd hello-world
touch main.py icon.svg
Write a typed extension
# main.py
from imperal_sdk import Extension, ChatExtension, ActionResult
from pydantic import BaseModel, Field
ext = Extension(
"hello-world",
version="1.0.0",
display_name="Hello World",
description="Demo extension that greets people by name with a friendly message.",
icon="icon.svg",
actions_explicit=True,
capabilities=["hello-world:read"],
)
chat = ChatExtension(
ext,
tool_name="hello_world",
description="Hello World — friendly greetings.",
)
class GreetParams(BaseModel):
name: str = Field(..., description="Person to greet")
@chat.function(
"greet",
description="Greet someone by name with a friendly message.",
action_type="read",
)
async def fn_greet(ctx, params: GreetParams) -> ActionResult:
return ActionResult.success(
data={"message": f"Hello, {params.name}! 🐝"},
summary=f"Greeted {params.name}",
)
That's the entire extension.
Validate, run, ship
imperal validate # 0 errors, 0 warnings — ready to publish
imperal dev # local sandbox
imperal build # generate imperal.json manifest
imperal deploy # upload to panel.imperal.io/developer
Once accepted in the Developer Portal, your extension appears in the Marketplace. Users install it with one click and Webbee starts calling it on their behalf.
→ Full walkthrough: docs.imperal.io/getting-started/quick-start
How extensions plug into Webbee
You: "send the Q3 report to Sarah"
│
▼
Imperal Panel (panel.imperal.io)
│ HTTPS
▼
Auth Gateway (auth.imperal.io) — checks who you are
│
▼
Webbee 🐝 — picks the extension(s) to call
│ typed dispatch
▼
mail extension → sends the email
│
▼
Webbee replies in chat: "Sent. ✅"
You write the extension. The platform handles auth, billing, LLM routing, multi-tenancy, audit, and recovery — for free.
The Federal Extension Contract
Every extension that ships through the Developer Portal must satisfy 11 federal validators (V14–V22 + V24, all ERROR severity). They guarantee the kernel can dispatch your typed functions directly — no LLM in the middle paraphrasing arguments, no silent write failures.
| Validator | Requires |
|---|---|
| V14 | Extension(description=...) ≥ 40 chars, ≠ app_id |
| V15 | Extension(display_name=...) ≥ 3 chars, ≠ app_id |
| V16 | Per-function description=... ≥ 20 chars |
| V17 | Pydantic BaseModel params on every @chat.function |
| V18 | Typed return — ActionResult or Pydantic model |
| V19 | actions_explicit=True + chain_callable=True on writes/destructive |
| V20 | effects=[...] declared on writes/destructive |
| V21 | XML-validated <svg> icon, ≤ 100 KB, viewBox required, no embedded raster |
| V22 | Lifecycle hook signatures match SDK contract |
| V24 | Handlers MUST NOT read ctx.skeleton.* — skeleton is LLM context only; use ctx.api |
→ Full reference: docs.imperal.io/sdk/validators-reference
What you get
| Capability | What it does |
|---|---|
| Typed functions | @chat.function with Pydantic params + ActionResult returns. Webbee dispatches typed calls — no LLM guessing, no silent write failures. |
| Pydantic feedback loop | If the LLM produces bad arguments, the SDK retries (max 2) with structured prose feedback. The next round usually fixes it. |
| Declarative UI | 55+ components — Stacks, Lists, Forms, Charts, DataTables. Build full Panel UI from Python. Zero React, zero rebuilds. |
| 11 SDK clients | ctx.store, ctx.ai, ctx.cache, ctx.http, ctx.config, ctx.notify, ctx.storage, ctx.extensions, ctx.skeleton (LLM-only), ctx.api, ctx.time |
| Lifecycle & events | @ext.on_install, @ext.on_event("mail.received"), @ext.schedule(cron=...), @ext.webhook(...) |
| Inter-extension calls | @ext.expose() + ctx.extensions.call("crm", "get_deal", id="d1") — typed cross-extension calls. |
| MockContext | Drop-in test replacement with 10 mock clients. Real assertions, no kernel required. |
| CLI | imperal init, imperal validate, imperal dev, imperal build, imperal deploy |
| BYOLLM | Users bring their own LLM keys. Anthropic, OpenAI, Google, Ollama — any OpenAI-compatible API. |
| Federal-grade by default | Tenant isolation, audit chokepoint, anti-hallucination guards, 117+ named runtime invariants — enforced by the kernel. |
Project structure
my-extension/
main.py Extension + @chat.function definitions
icon.svg Required (V21 — XML <svg> root + viewBox, ≤ 100 KB)
imperal.json Manifest (auto-generated by `imperal build`)
pyproject.toml imperal-sdk >= 4.0.0
tests/
test_main.py Tests using MockContext
Testing without a server
from imperal_sdk.testing import MockContext
async def test_greet():
ctx = MockContext()
result = await fn_greet(ctx, GreetParams(name="Alex"))
assert result.status == "success"
assert "Alex" in result.data["message"]
MockContext ships drop-in replacements for ctx.store, ctx.http, ctx.ai, ctx.notify, ctx.cache, ctx.config, ctx.storage, ctx.skeleton, ctx.extensions, and ctx.time. Real assertions, no kernel.
Where to go next
- Build something real → Your First Real Extension — typed params, panels, audit, secrets.
- Master the contract → Federal Extension Contract — what every extension MUST satisfy.
- Copy-paste recipes → Recipes — sending mail, querying DBs, multi-step chains, BYOLLM.
- Reference → SDK reference — every decorator, every client, every component.
Links
| Website | imperal.io |
| Documentation | docs.imperal.io |
| PyPI | pypi.org/project/imperal-sdk |
| Changelog | CHANGELOG.md |
| Source | github.com/imperalcloud/imperal-sdk |
| License | AGPL-3.0 |
Built by Imperal, Inc. · Webbee 🐝 is its agent.
1 maintainer
Metadata
1 maintainer
Release files for imperal-sdk 4.2.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| imperal_sdk-4.2.2.tar.gz | 541.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| imperal_sdk-4.2.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 755.2 kB
Release files / imperal_sdk-4.2.2.tar.gz
| Download URL | imperal_sdk-4.2.2.tar.gz |
|---|---|
| Size | 541.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
42366013bd2f718740b453b761554805353f22096d325063bbe095c9f8fa31e8
|
|
BLAKE2b-256 checksum How to use checksums |
b1f24bd5fc2d5b33b099ab979b8769788c80e462bca4492fc51438742867e2b5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 12, 2026.
Transparency logRelease files / imperal_sdk-4.2.2-py3-none-any.whl
| Download URL | imperal_sdk-4.2.2-py3-none-any.whl |
|---|---|
| Size | 213.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e107a9d0f13e8a1485b07293846f9961280bb215019c219d85e91a4c2abf6fc2
|
|
BLAKE2b-256 checksum How to use checksums |
64cfa33869f185b3e49515d92459464bc7f739b4c3f56115f65032305fa8eec4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 12, 2026.
Transparency log
