Skip to main content

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.

PyPI Python Tests License

Quickstart · Documentation · PyPI · imperal.io


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


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.

Metadata

Release files for imperal-sdk 4.2.10

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for imperal-sdk 4.2.10
File Size Uploaded Provenance Actions
imperal_sdk-4.2.10.tar.gz 550.6 kB With provenance Details for imperal_sdk-4.2.10.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for imperal-sdk 4.2.10
File Interpreter ABI Platform Actions
imperal_sdk-4.2.10-py3-none-any.whl Python 3 none any Details for imperal_sdk-4.2.10-py3-none-any.whl

Total release size: 770.0 kB

Release files / imperal_sdk-4.2.10.tar.gz

Download URL imperal_sdk-4.2.10.tar.gz
Size 550.6 kB
Tags Source
SHA-256 checksum
How to use checksums
07c31e15add1e837b68f62862e66af37c54e65b97c73e3b6a7fb684b10251ae6
BLAKE2b-256 checksum
How to use checksums
7a3b5a2ced90cef61bea8552ce65d938b6585dad82280dc93845c59e09daec0d
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 13, 2026.

Transparency log

Release files / imperal_sdk-4.2.10-py3-none-any.whl

Download URL imperal_sdk-4.2.10-py3-none-any.whl
Size 219.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1cc49135407f72629cd926c53e2ef98b9761578c14d3d4c678b1c93e0f30f878
BLAKE2b-256 checksum
How to use checksums
cb158707c7277ef0be5cd0eee16acd6f65e65e0d6726f95b7fbcb333fe13a513
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 13, 2026.

Transparency log

Security for imperal-sdk 4.2.10

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for imperal_sdk-4.2.10.tar.gz

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 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

4.2.10 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page