Imperal SDK: The API Surface for Building on Imperal

What the Imperal SDK Actually Is

The Imperal SDK is a Python package. You install it the way you'd install any other library:

pip install imperal-sdk

It's AGPL-3.0 licensed, with a commercial license available for teams that need to ship closed-source extensions. That's the legal shape of it. The more interesting part is the architectural shape.

The SDK is the only API surface a developer needs to build on Imperal. Auth, billing, storage, LLM routing, panel rendering, marketplace integration, validation, observability, all handled by the runtime, not by you. That means consistent, auditable behavior across every extension, not bespoke logic per developer.

This is the same logic that runs through the rest of Imperal's design: the model proposes, the kernel decides. When you write an extension, you register proposals, structured, typed requests that the kernel evaluates. The runtime decides whether that action actually happens. This is the same boundary that governs Webbee's own actions: a wrong guess doesn't reach the delete. Extension developers inherit that boundary automatically, you don't have to build it, and you can't accidentally bypass it.

Concretely, that boundary is one decorator. Every tool a developer registers declares its action_type up front, read (no side effects, no confirmation), write (side-effecting, audited), or destructive (irreversible, always confirmed), and the runtime enforces the consequences of that declaration, not the developer's code:

from imperal_sdk import ChatExtension, ActionResult
from pydantic import BaseModel, Field

class ClearDoneParams(BaseModel):
    confirm: bool = Field(False, description="Set true to actually clear (safety gate)")

@chat.function(
    "clear_done_tasks",
    action_type="destructive",  # kernel gates this behind a confirmation card
    description="Permanently remove all completed tasks.",
)
async def clear_done_tasks(ctx, params: ClearDoneParams) -> ActionResult:
    count = clear_done(ctx.user.imperal_id)
    return ActionResult.success(
        data={"cleared": count},
        summary=f"Cleared {count} completed task(s).",
    )

The developer never writes the confirmation flow, the audit row, or the retry-on-bad-input logic, declaring action_type="destructive" is what makes the kernel demand a yes before this ever runs.

This Is Running in Production, Not a Roadmap Slide

None of this is theoretical. A full suite of extensions already runs on the Imperal SDK today: admin, billing, developer portal, mail, notes, automations, web-tools, and more. These aren't demo stubs, they're deployed through the KAV validation pipeline and serving real users on the live Webbee instance right now.

That matters because a lot of developer tooling in this space gets announced years before it's load-bearing. Imperal's SDK is load-bearing today. The extensions listed above are the ones running Webbee's own admin surface, billing, and day-to-day utility functions, if the SDK couldn't handle production traffic and real validation constraints, those extensions wouldn't be live. They are.

The Economics: Actions Cost Tokens, Not Seats

Developers publish extensions to the marketplace. Users install them, free or paid, developer's choice. But the pricing model underneath isn't a subscription tier or a seat license. It's action-based: every tool call, every action an extension performs, costs tokens with a fixed dollar value attached.

Revenue splits 80% to the developer, 20% to the platform. The point of anchoring pricing to actions rather than seats is that it lines up incentives with actual usage. A user who runs an extension once a month costs less, and generates less revenue, than one running it constantly, a more honest reflection of value delivered than a flat monthly fee regardless of use.

For developers, this means the economics of an extension are legible from day one: you know what an action costs, you know your cut, and you know the runtime is the one metering and billing for it. You don't have to build billing infrastructure to get paid. That's part of the SDK's job, not yours.

What You Get for Free

Building on the Imperal SDK means the runtime hands you a set of infrastructure pieces that you'd otherwise have to build, secure, and maintain yourself:

• Auth, you never handle credentials or sessions directly.
• Storage in two tiers, no need to stand up a database just to persist state.
• A durable workflow engine that survives restarts, so long-running or multi-step actions don't vanish on failure.
• LLM routing. Model selection, keys, fallback logic, all handled upstream of your code.
• Billing, metering, and payouts, so you never touch a payments API.
• Panel rendering puts your extension's UI inside Webbee without custom frontend plumbing.
• Skeleton management for the scaffolding that ties an extension's structure together.
• A 20-check deploy pipeline validates what you ship before it ever reaches production.

Each of these is a category of work that normally eats weeks of engineering time before a developer writes a single line of the feature they actually care about. The SDK strips that away. You write what your extension does. The runtime handles how it runs.

Start Building

The Imperal SDK exists so that building a real, production-grade extension doesn't require reinventing auth, billing, or a validation pipeline first. Install the package, read the docs, and register your first proposal. The runtime takes it from there, the same way it does for the admin, billing, mail, notes, automations, and web-tools extensions already running on the live Webbee instance today.

pip install imperal-sdk

Then read the SDK docs and build your first extension.