castella 0.8.0

Castella is a pure Python cross-platform UI framework

Castella

Castella is a pure Python cross-platform UI framework.

Documentation Site Examples Slides

Goals

The primary final goal of Castella is to provide features for Python programmers easy to create a UI application for several OS platforms and web browsers in a single most same code as possible as. The second goal is to provide a UI framework that Python programmers can easily understand, modify, and extend as needed.

Features

• The core part as a UI framework of Castella is written in only Python. It's not a wrapper for existing something written in other programing languages. "pure Python cross-platform UI framework" specifies things like the above.
• Castella allows pythonista to define UI declaratively in Python.
• Castella provides hot-reloading or hot-restarting on development.
• Deep Pydantic v2 integration - 70+ Pydantic models power the entire framework:
  • Core types: geometry (Point, Size, Rect), fonts, styles with immutable patterns
  • Chart data models with observable patterns and automatic UI updates
  • A2UI/A2A/MCP protocol types with validation and serialization
  • Theme system with design tokens (ColorPalette, Typography, Spacing)
  • DataTable: from_pydantic() extracts Field.title, Field.description (tooltips), and type annotations (column width inference)
• Comprehensive theme system with design tokens (colors, typography, spacing).
• Built-in themes: Tokyo Night (default), Cupertino, Material Design 3, and classic Castella themes.
• Dark/light mode with automatic system detection and runtime switching.
• Rounded corners and shadows support for modern UI aesthetics.
• Custom themes via Theme.derive() for partial overrides or full ColorPalette customization.
• Rich markdown rendering with syntax highlighting and LaTeX math support.
• Multi-line text editor with scrolling, cursor positioning, text selection, and clipboard support (copy/cut/paste).
• Native interactive charts (Bar, Line, Pie, Scatter, Area, Stacked Bar, Gauge, Heatmap) with tooltips, hover, click events, and smooth curves.
• Heatmap support - Both chart (HeatmapChart) and table (HeatmapConfig) variants with Viridis, Plasma, Inferno, Magma colormaps.
• ASCII charts for terminal environments (Bar, Pie, Line, Gauge).
• Animation system - Smooth property animations with ValueTween, AnimatedState, and easing functions.
• ProgressBar widget - Animated progress indicator with customizable colors.
• Widget lifecycle hooks - on_mount/on_unmount for resource management (timers, subscriptions).
• State preservation - ListState.map_cached() and Component.cache() preserve widget state across view rebuilds.
• Castella utilizes GPU via dependent libraries.
• Z-index support enables layered UIs with modals, popups, and overlays.
• A2A Protocol support - Connect to AI agents via Google's Agent-to-Agent protocol with A2AClient.
• A2UI Protocol support - Render agent-generated UIs with 17 standard components, tested with Google's sample agents.
• MCP (Model Context Protocol) support - AI agents can introspect and control UIs programmatically via MCP.
• AgentChat - Build chat interfaces with AI agents in just 3 lines of code.
• Agent Skills - AI coding agents can learn Castella via 5 built-in skills.
• Workflow Studio Samples - Demo applications showcasing visual development environments for AI workflow frameworks.

Workflow Studio Samples

Castella includes sample applications demonstrating visual development environments for popular AI workflow frameworks. These are located in examples/ and serve as references for building your own workflow visualization tools.

Sample	Framework	Features
langgraph_studio/	LangGraph	Graph visualization, step execution, state inspection
llamaindex_studio/	LlamaIndex Workflows	Workflow visualization, breakpoints, execution history
pydantic_graph_studio/	pydantic-graph	Graph structure visualization, step-by-step execution
edda_workflow_manager/	Edda + LlamaIndex Workflows	Workflow management, execution history, live monitoring

# Run LangGraph Studio sample
uv run python -m examples.langgraph_studio.main

# Run LlamaIndex Workflow Studio sample
uv run python examples/llamaindex_studio/main.py

# Run pydantic-graph Studio sample
uv run python -m examples.pydantic_graph_studio.main

# Run Edda Workflow Manager sample
uv run python examples/edda_workflow_manager/main.py --db sqlite+aiosqlite:///path/to/edda.db

Agent Skills

Castella includes Agent Skills to help AI coding agents effectively use the framework. Located in skills/:

Skill	Description
castella-core	Core UI development - widgets, components, state, layouts, themes
castella-a2ui	A2UI JSON rendering - parse messages, data binding, progressive rendering
castella-a2a	A2A protocol - connect to agents, agent cards, streaming responses
castella-mcp	MCP integration - servers, resources, tools, semantic IDs
castella-agent-ui	Agent UI components - AgentChat, MultiAgentChat, AgentHub

Each skill follows the agentskills.io specification with:

• SKILL.md - Main skill document with quick start and patterns
• references/ - Detailed API documentation
• scripts/ - Executable examples

Dependencies

• For desktop platforms, Castella is standing on existing excellent python bindings for window management library (GLFW or SDL2) and 2D graphics library (Skia).
• For web browsers, Castella is standing on awesome Pyodide/PyScript and CanvasKit (Wasm version of Skia).
• For terminals, Castella is standing on prompt_toolkit.

Quick Start

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a new project
uv init my-app && cd my-app

# Add Castella with GLFW backend
uv add "castella[glfw]"

# Run your app
uv run python your_app.py

For detailed installation instructions (SDL2, TUI, web), see the Getting Started Guide.

An example of code using Castella

from castella import App, Button, Column, Component, Row, State, Text
from castella.frame import Frame


class Counter(Component):
    def __init__(self):
        super().__init__()
        self._count = State(0)

    def view(self):
        return Column(
            Text(self._count),
            Row(
                Button("Up", font_size=50).on_click(self.up),
                Button("Down", font_size=50).on_click(self.down),
            ),
        )

    def up(self, _):
        self._count += 1

    def down(self, _):
        self._count -= 1


App(Frame("Counter", 800, 600), Counter()).run()

Watch a very short demo video

Animation Example

Animate values with easing functions:

from castella import App, Column, Component, Button, ProgressBar, ProgressBarState
from castella.animation import ValueTween, AnimationScheduler, EasingFunction
from castella.frame import Frame


class AnimationDemo(Component):
    def __init__(self):
        super().__init__()
        self._progress = ProgressBarState(0, min_val=0, max_val=100)
        self._progress.attach(self)

    def view(self):
        return Column(
            ProgressBar(self._progress).fixed_height(24),
            Button("Animate").on_click(self._animate),
        )

    def _animate(self, _):
        self._progress.set(0)
        AnimationScheduler.get().add(
            ValueTween(
                from_value=0,
                to_value=100,
                duration_ms=1000,
                easing=EasingFunction.EASE_OUT_CUBIC,
                on_update=lambda v: self._progress.set(v),
            )
        )


App(Frame("Animation", 400, 200), AnimationDemo()).run()

Agent Chat Example

Build a chat UI for AI agents in just 3 lines:

from castella.agent import AgentChat

# Connect to an A2A-compatible agent
chat = AgentChat.from_a2a("http://localhost:8080")
chat.run()

# Or use a custom handler
chat = AgentChat(
    handler=lambda msg: f"You said: {msg}",
    title="My Bot",
)
chat.run()

A2UI Example

Render AI-generated UIs from A2UI compatible agents:

from castella import App
from castella.a2ui import A2UIClient, A2UIComponent
from castella.frame import Frame

# Connect to an A2UI-enabled agent
client = A2UIClient("http://localhost:10002")

# Send a message and get UI
surface = client.send("Find me restaurants in Tokyo")

# Render in Castella
if surface:
    App(Frame("A2UI Demo", 800, 600), A2UIComponent(surface)).run()

MCP Example

Enable AI agents to control your UI via MCP (Model Context Protocol):

from castella import App, Column, Button, Input, Text
from castella.frame import Frame
from castella.mcp import CastellaMCPServer

def build_ui():
    return Column(
        Text("Hello MCP!"),
        Input("").semantic_id("name-input"),
        Button("Submit").semantic_id("submit-btn"),
    )

app = App(Frame("MCP Demo", 800, 600), build_ui())
mcp = CastellaMCPServer(app, name="my-app")

# Run SSE server for HTTP clients
mcp.run_sse_in_background(host="localhost", port=8765)

app.run()

AI agents can then introspect the UI tree and control widgets:

# Client example (AI agent)
call_tool("type_text", element_id="name-input", text="Hello")
call_tool("click", element_id="submit-btn")

Pydantic Integration Example

Leverage Pydantic's Field metadata for automatic DataTable configuration:

from pydantic import BaseModel, Field
from castella import App, DataTable, DataTableState
from castella.frame import Frame


class Employee(BaseModel):
    id: int = Field(..., title="ID", description="Unique identifier")
    name: str = Field(..., title="Name", description="Full name")
    salary: float = Field(..., title="Salary", description="Annual salary")


employees = [
    Employee(id=1, name="Alice", salary=75000.0),
    Employee(id=2, name="Bob", salary=85000.0),
]

# Field.title → column name, Field.description → tooltip, type → column width
state = DataTableState.from_pydantic(employees)

# Fluent API for per-table styling
table = (
    DataTable(state)
    .header_bg_color("#3d5a80")
    .header_text_color("#ffffff")
    .selected_bg_color("#ee6c4d")
)

App(Frame("Employee Table", 600, 400), table).run()

You can see some other examples in examples directory.

Supported Platforms

Currently, Castella theoretically should support not-too-old versions of the following platforms.

• Windows 10/11
• Mac OS X
• Linux
• Web browsers
• Terminals

License

MIT License

Copyright (c) 2022 Yasushi Itoh

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.