Components showcase

Every Fumadocs UI component used across the Imperal Cloud docs, shown in action on one page — cards, callouts, tabs and more to copy-paste when authoring.

This is a single-page demo of every Fumadocs UI component used across these docs. If you're authoring or porting docs, copy-paste from here.

Cards

<Cards>
  <Card icon="🚀" title="Title" href="/en/..." description="..." />
</Cards>

🚀

Get started

Build, test, and run a real extension in 5 minutes.

🧠

Architecture

The full path from chat message to your handler.

📐

Federal contract

What every extension must satisfy — V1-V24 + V24-AST + V31.

🛡️

Federal invariants

The 117+ named runtime guarantees.

Steps

<Steps>
  <Step>### Title — content</Step>
</Steps>

Install the SDK

pip install imperal-sdk

Define a Pydantic model

class GreetParams(BaseModel):
    name: str = Field(description="Person to greet")

Register a handler

@chat.function("greet", description="Greet a person by name")
async def greet(ctx, params) -> ActionResult:
    return ActionResult.ok(message=f"Hello, {params.name}!")

Publish

imperal build .
imperal validate .
# Then upload at panel.imperal.io/developer

Tabs

<Tabs items={['Python', 'Bash', 'JSON']}>
  <Tab value="Python">...</Tab>
</Tabs>

async def greet(ctx, params):
    return {"text": f"Hello, {params.name}! 🐝"}

imperal test --tool greet --args '{"name": "Alex"}'

{ "text": "Hello, Alex! 🐝" }

Callouts

<Callout type="info|warn|error">...</Callout>

Info callout

Neutral information. Use this for caveats, references, or expansion of a point made in main text.

Warning

Something the reader should be careful about. Common federal-discipline pitfalls live here.

Critical / banned pattern

Do not do this. Federal blocker, security risk, or a known-bad pattern that breaks invariants.

Files (project structure)

<Files>
  <Folder name="my-ext" defaultOpen>
    <File name="app.py" icon="🐍" />
  </Folder>
</Files>

🐍app.py

📋imperal.json

🐍schemas.py

🌍i18n.json

📖README.md

Accordions

<Accordions>
  <Accordion title="Question?">Answer body.</Accordion>
</Accordions>

TypeTable

<TypeTable
  type={{
    fieldName: { type: "...", default: "...", description: "..." },
  }}
/>

Prop

Type

Tables (Markdown)

| Header | Header |
|--------|--------|
| cell   | cell   |

Class	Severity	After v4.0+
Silent write failures	🔴 critical	✅ closed — typed dispatch
Hallucinated IDs	🔴 critical	✅ closed — anti-hallucination grounding + V17
Confirmation bypass	🔴 critical	✅ closed — typed-iterate
Lifecycle TypeError	🟠 high	✅ closed for new publishes — V22

Code blocks with title

```python title="app.py"
print("hi")
```

app.py

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

class GreetParams(BaseModel):
    name: str = Field(description="Person to greet")

class Greeting(sdl.Entity, sdl.Bodied):
    pass

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,
)

chat = ChatExtension(ext, tool_name="tool_hello_world_chat", description="Hello World — friendly greetings.")

@chat.function(
    "greet",
    action_type="read",
    description="Greet someone by name with a friendly message.",
    data_model=Greeting,   # V23: read tools declare a typed SDL return
)
async def greet(ctx, params: GreetParams) -> ActionResult:
    return ActionResult.success(
        Greeting(id="greeting", title=f"Hello, {params.name}!", body=f"Hello, {params.name}! 🐝"),
        summary=f"Greeted {params.name}.",
    )

Code blocks with language

pip install imperal-sdk
imperal build
imperal test --tool greet --args '{"name": "Alex"}'

{
  "schema_version": 3,
  "name": "hello-world",
  "actions_explicit": true,
  "tools": [
    { "name": "greet", "action_type": "read" }
  ]
}

- old_action = "destructive"
+ new_action = "destructive"
+ id_projection = "folder_id"   ← v4.1.2 federal-clean

Inline code and emphasis

Use inline code for identifiers, bold for emphasis, italics for terms or quotes.

Block quotes for user-facing text or citations.

ASCII diagrams in fenced blocks

USER (browser)
   │
   ▼
AUTH GATEWAY  (auth.imperal.io)
   │
   ▼
WEBBEE WEB-KERNEL
   │
   ▼
YOUR EXTENSION

Mixing it together

A real example combining components:

Define a typed handler

class CreateNoteParams(BaseModel):
    title: str = Field(description="Short title.")
    content_text: str = Field(description="Full note content — write the actual content.")

from imperal_sdk import sdl, ActionResult

class Note(sdl.Entity, sdl.Bodied):
    pass

@chat.function(
    "create_note",
    description="Create a note in the user's notebook.",
    action_type="write",
    data_model=Note,   # V24: write tools should declare a typed SDL return
)
async def create_note(ctx, params: CreateNoteParams) -> ActionResult:
    resp = await ctx.http.post("/notes", json=params.model_dump())
    note = resp.json()
    return ActionResult.success(
        Note(id=note["id"], title=note["title"], body=params.content_text),
        summary=f"Created note: {note['title']}",
    )

Validate

imperal validate

Federal validators run

V1-V24 + V24-AST + V31 — most are ERROR (a failing ERROR blocks publish); V10/V20/V23/V24 are WARN. See the validators reference.

Publish

imperal build .
imperal validate .
# Then upload at panel.imperal.io/developer

Where to next

🚀

Quick Start

Use these components for real — build a working extension in 5 minutes.

🛠️

Building Extensions

Long-form walkthrough applying these patterns end to end.

📐

Federal Contract

What every extension must satisfy.

Components showcase

Get started

Architecture

Federal contract

Federal invariants

What's an extension?

Where does my code run?

How do I test locally?

Quick Start

Building Extensions

Federal Contract

On this page