{"id":19787939,"url":"https://github.com/i2y/castella","last_synced_at":"2026-01-23T14:49:56.932Z","repository":{"id":40049693,"uuid":"494810655","full_name":"i2y/castella","owner":"i2y","description":"Castella is a cross-platform pure Python UI framework","archived":false,"fork":false,"pushed_at":"2026-01-16T15:23:53.000Z","size":22660,"stargazers_count":34,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-16T22:47:53.693Z","etag":null,"topics":["cross-platform","gui","python","ui"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/i2y.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-05-21T14:45:30.000Z","updated_at":"2026-01-16T15:23:39.000Z","dependencies_parsed_at":"2025-05-01T00:32:05.167Z","dependency_job_id":"490cba9a-6d43-4826-b713-9ad123826499","html_url":"https://github.com/i2y/castella","commit_stats":null,"previous_names":["i2y/cattt"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/i2y/castella","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i2y%2Fcastella","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i2y%2Fcastella/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i2y%2Fcastella/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i2y%2Fcastella/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/i2y","download_url":"https://codeload.github.com/i2y/castella/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i2y%2Fcastella/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28694457,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-23T14:15:13.573Z","status":"ssl_error","status_checked_at":"2026-01-23T14:09:05.534Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cross-platform","gui","python","ui"],"created_at":"2024-11-12T06:25:13.786Z","updated_at":"2026-01-23T14:49:56.915Z","avatar_url":"https://github.com/i2y.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Castella\nCastella is a pure Python cross-platform UI framework.\n\n\u003cimg src=\"https://user-images.githubusercontent.com/6240399/174487936-8484be0e-b2b5-433c-9416-594c0fd57f3a.png\" style=\"height: 1em;\"\u003e\u003c/img\u003e [Documentation Site](https://i2y.github.io/castella) \u003cimg src=\"https://user-images.githubusercontent.com/6240399/174487787-7099167f-a8ad-42e8-9362-c19c84dc81be.png\" style=\"height: 1em;\"\u003e\u003c/img\u003e [Examples](examples) \u003cimg src=\"https://user-images.githubusercontent.com/6240399/174487787-7099167f-a8ad-42e8-9362-c19c84dc81be.png\" style=\"height: 1em;\"\u003e\u003c/img\u003e [Slides](https://speakerdeck.com/i2y/a-cross-platform-pure-python-declarative-ui-framework)\n\n## Goals\nThe 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.\n\n## Features\n- 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.\n- Castella allows pythonista to define UI declaratively in Python.\n- Castella provides hot-reloading or hot-restarting on development.\n- **Deep Pydantic v2 integration** - 70+ Pydantic models power the entire framework:\n  - Core types: geometry (`Point`, `Size`, `Rect`), fonts, styles with immutable patterns\n  - Chart data models with observable patterns and automatic UI updates\n  - A2UI/A2A/MCP protocol types with validation and serialization\n  - Theme system with design tokens (`ColorPalette`, `Typography`, `Spacing`)\n  - DataTable: `from_pydantic()` extracts `Field.title`, `Field.description` (tooltips), and type annotations (column width inference)\n- Comprehensive theme system with design tokens (colors, typography, spacing).\n- Built-in themes: Tokyo Night (default), Cupertino, Material Design 3, and classic Castella themes.\n- Dark/light mode with automatic system detection and runtime switching.\n- Rounded corners and shadows support for modern UI aesthetics.\n- Custom themes via `Theme.derive()` for partial overrides or full `ColorPalette` customization.\n- Rich markdown rendering with syntax highlighting and LaTeX math support.\n- Multi-line text editor with scrolling, cursor positioning, text selection, and clipboard support (copy/cut/paste).\n- Native interactive charts (Bar, Line, Pie, Scatter, Area, Stacked Bar, Gauge, Heatmap) with tooltips, hover, click events, and smooth curves.\n- **Heatmap support** - Both chart (`HeatmapChart`) and table (`HeatmapConfig`) variants with Viridis, Plasma, Inferno, Magma colormaps.\n- ASCII charts for terminal environments (Bar, Pie, Line, Gauge).\n- **Animation system** - Smooth property animations with `ValueTween`, `AnimatedState`, and easing functions.\n- **Audio playback** - Cross-platform audio support with `AudioPlayer` widget and `AudioManager` API (MP3, OGG, WAV).\n- **ProgressBar widget** - Animated progress indicator with customizable colors.\n- **Widget lifecycle hooks** - `on_mount`/`on_unmount` for resource management (timers, subscriptions).\n- **State preservation** - `ListState.map_cached()` and `Component.cache()` preserve widget state across view rebuilds.\n- Castella utilizes GPU via dependent libraries.\n- Z-index support enables layered UIs with modals, popups, and overlays.\n- **A2A Protocol support** - Connect to AI agents via Google's Agent-to-Agent protocol with `A2AClient`.\n- **A2UI Protocol support** - Render agent-generated UIs with 17 standard components, tested with Google's sample agents.\n- **MCP (Model Context Protocol) support** - AI agents can introspect and control UIs programmatically via MCP.\n- **AgentChat** - Build chat interfaces with AI agents in just 3 lines of code.\n- **Agent Skills** - AI coding agents can learn Castella via 5 built-in skills.\n- **Workflow Studio Samples** - Demo applications showcasing visual development environments for AI workflow frameworks.\n- **Internationalization (i18n)** - Runtime locale switching with YAML translations, reactive `LocaleString`, and pluralization support.\n\n## Workflow Studio Samples\n\nCastella 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.\n\n| Sample | Framework | Features |\n|--------|-----------|----------|\n| `langgraph_studio/` | [LangGraph](https://github.com/langchain-ai/langgraph) | Graph visualization, step execution, state inspection |\n| `llamaindex_studio/` | [LlamaIndex Workflows](https://docs.llamaindex.ai/en/stable/module_guides/workflow/) | Workflow visualization, breakpoints, execution history |\n| `pydantic_graph_studio/` | [pydantic-graph](https://ai.pydantic.dev/pydantic-graph/) | Graph structure visualization, step-by-step execution |\n| `edda_workflow_manager/` | [Edda](https://github.com/i2y/edda) + [LlamaIndex Workflows](https://docs.llamaindex.ai/en/stable/module_guides/workflow/) | Workflow management, execution history, live monitoring |\n\n```bash\n# Run LangGraph Studio sample\nuv run python -m examples.langgraph_studio.main\n\n# Run LlamaIndex Workflow Studio sample\nuv run python examples/llamaindex_studio/main.py\n\n# Run pydantic-graph Studio sample\nuv run python -m examples.pydantic_graph_studio.main\n\n# Run Edda Workflow Manager sample\nuv run python examples/edda_workflow_manager/main.py --db sqlite+aiosqlite:///path/to/edda.db\n```\n\n## Agent Skills\n\nCastella includes [Agent Skills](https://agentskills.io/) to help AI coding agents effectively use the framework. Located in `skills/`:\n\n| Skill | Description |\n|-------|-------------|\n| `castella-core` | Core UI development - widgets, components, state, layouts, themes |\n| `castella-a2ui` | A2UI JSON rendering - parse messages, data binding, progressive rendering |\n| `castella-a2a` | A2A protocol - connect to agents, agent cards, streaming responses |\n| `castella-mcp` | MCP integration - servers, resources, tools, semantic IDs |\n| `castella-agent-ui` | Agent UI components - AgentChat, MultiAgentChat, AgentHub |\n\nEach skill follows the [agentskills.io specification](https://agentskills.io/specification) with:\n- `SKILL.md` - Main skill document with quick start and patterns\n- `references/` - Detailed API documentation\n- `scripts/` - Executable examples\n\n## Dependencies\n- For desktop platforms, Castella is standing on existing excellent python bindings for window management library (GLFW, SDL2, or SDL3) and 2D graphics library (Skia).\n- For web browsers, Castella is standing on awesome Pyodide/PyScript and CanvasKit (Wasm version of Skia).\n- For terminals, Castella is standing on prompt_toolkit.\n\n## Quick Start\n\n```bash\n# Install uv (if not already installed)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Create a new project\nuv init my-app \u0026\u0026 cd my-app\n\n# Add Castella (choose your backend)\nuv add \"castella[sdl3]\"  # For easy setup (all platforms, no extra install)\nuv add \"castella[sdl]\"   # For easy setup (SDL2 stable alternative)\nuv add \"castella[glfw]\"  # For better performance\n\n# Run your app\nuv run python your_app.py\n```\n\n### Platform Recommendations\n\n| Platform | Easy Setup | Better Performance |\n|----------|------------|------------------|\n| **Windows** | `castella[sdl3]` or `castella[sdl]` | `castella[glfw]` (requires [GLFW install](https://www.glfw.org/download.html)) |\n| **Linux** | `castella[sdl3]` or `castella[sdl]` | `castella[glfw]` (requires `apt install libglfw3-dev`) |\n| **macOS** | All backends work without extra install | `castella[glfw]` |\n\n### IME Support (Japanese/Chinese/Korean Input)\n\nAll backends support IME on all platforms. On macOS, GLFW provides better IME integration via native Cocoa APIs.\n\nFor detailed installation instructions (TUI, web), see the [Getting Started Guide](https://i2y.github.io/castella/getting-started/).\n\n## An example of code using Castella\n\n```python\nfrom castella import App, Button, Column, Component, Row, State, Text\nfrom castella.frame import Frame\n\n\nclass Counter(Component):\n    def __init__(self):\n        super().__init__()\n        self._count = State(0)\n\n    def view(self):\n        return Column(\n            Text(self._count),\n            Row(\n                Button(\"Up\", font_size=50).on_click(self.up),\n                Button(\"Down\", font_size=50).on_click(self.down),\n            ),\n        )\n\n    def up(self, _):\n        self._count += 1\n\n    def down(self, _):\n        self._count -= 1\n\n\nApp(Frame(\"Counter\", 800, 600), Counter()).run()\n```\n[Watch a very short demo video](docs/videos/demo.mp4)\n\n## Animation Example\n\nAnimate values with easing functions:\n\n```python\nfrom castella import App, Column, Component, Button, ProgressBar, ProgressBarState\nfrom castella.animation import ValueTween, AnimationScheduler, EasingFunction\nfrom castella.frame import Frame\n\n\nclass AnimationDemo(Component):\n    def __init__(self):\n        super().__init__()\n        self._progress = ProgressBarState(0, min_val=0, max_val=100)\n        self._progress.attach(self)\n\n    def view(self):\n        return Column(\n            ProgressBar(self._progress).fixed_height(24),\n            Button(\"Animate\").on_click(self._animate),\n        )\n\n    def _animate(self, _):\n        self._progress.set(0)\n        AnimationScheduler.get().add(\n            ValueTween(\n                from_value=0,\n                to_value=100,\n                duration_ms=1000,\n                easing=EasingFunction.EASE_OUT_CUBIC,\n                on_update=lambda v: self._progress.set(v),\n            )\n        )\n\n\nApp(Frame(\"Animation\", 400, 200), AnimationDemo()).run()\n```\n\n## Audio Player Example\n\nPlay audio files with the built-in `AudioPlayer` widget:\n\n```python\nfrom castella import App\nfrom castella.audio import AudioPlayer\nfrom castella.frame import Frame\n\n# Simple audio player with full controls\nplayer = AudioPlayer(\"music.mp3\")\nplayer.on_ended(lambda: print(\"Playback finished!\"))\n\nApp(Frame(\"Audio Player\", 500, 200), player).run()\n```\n\nOr use the low-level `AudioManager` API for custom audio handling:\n\n```python\nfrom castella.audio import AudioManager\n\nmanager = AudioManager.get()\nhandle, state = manager.load(\"sound.wav\")\n\nmanager.play(handle)\nmanager.set_volume(handle, 0.5)  # 50% volume\nmanager.seek(handle, 5000)      # Seek to 5 seconds\n```\n\nInstallation: `uv add \"castella[audio]\"` (or included with `castella[sdl]`/`castella[sdl3]`)\n\n## Agent Chat Example\n\nBuild a chat UI for AI agents in just 3 lines:\n\n```python\nfrom castella.agent import AgentChat\n\n# Connect to an A2A-compatible agent\nchat = AgentChat.from_a2a(\"http://localhost:8080\")\nchat.run()\n\n# Or use a custom handler\nchat = AgentChat(\n    handler=lambda msg: f\"You said: {msg}\",\n    title=\"My Bot\",\n)\nchat.run()\n```\n\n## A2UI Example\n\nRender AI-generated UIs from [A2UI](https://a2ui.org/) compatible agents:\n\n```python\nfrom castella import App\nfrom castella.a2ui import A2UIClient, A2UIComponent\nfrom castella.frame import Frame\n\n# Connect to an A2UI-enabled agent\nclient = A2UIClient(\"http://localhost:10002\")\n\n# Send a message and get UI\nsurface = client.send(\"Find me restaurants in Tokyo\")\n\n# Render in Castella\nif surface:\n    App(Frame(\"A2UI Demo\", 800, 600), A2UIComponent(surface)).run()\n```\n\n## MCP Example\n\nEnable AI agents to control your UI via [MCP (Model Context Protocol)](https://modelcontextprotocol.github.io/):\n\n```python\nfrom castella import App, Column, Button, Input, Text\nfrom castella.frame import Frame\nfrom castella.mcp import CastellaMCPServer\n\ndef build_ui():\n    return Column(\n        Text(\"Hello MCP!\"),\n        Input(\"\").semantic_id(\"name-input\"),\n        Button(\"Submit\").semantic_id(\"submit-btn\"),\n    )\n\napp = App(Frame(\"MCP Demo\", 800, 600), build_ui())\nmcp = CastellaMCPServer(app, name=\"my-app\")\n\n# Run SSE server for HTTP clients\nmcp.run_sse_in_background(host=\"localhost\", port=8765)\n\napp.run()\n```\n\nAI agents can then introspect the UI tree and control widgets:\n```python\n# Client example (AI agent)\ncall_tool(\"type_text\", element_id=\"name-input\", text=\"Hello\")\ncall_tool(\"click\", element_id=\"submit-btn\")\n```\n\n## Pydantic Integration Example\n\nLeverage Pydantic's `Field` metadata for automatic DataTable configuration:\n\n```python\nfrom pydantic import BaseModel, Field\nfrom castella import App, DataTable, DataTableState\nfrom castella.frame import Frame\n\n\nclass Employee(BaseModel):\n    id: int = Field(..., title=\"ID\", description=\"Unique identifier\")\n    name: str = Field(..., title=\"Name\", description=\"Full name\")\n    salary: float = Field(..., title=\"Salary\", description=\"Annual salary\")\n\n\nemployees = [\n    Employee(id=1, name=\"Alice\", salary=75000.0),\n    Employee(id=2, name=\"Bob\", salary=85000.0),\n]\n\n# Field.title → column name, Field.description → tooltip, type → column width\nstate = DataTableState.from_pydantic(employees)\n\n# Fluent API for per-table styling\ntable = (\n    DataTable(state)\n    .header_bg_color(\"#3d5a80\")\n    .header_text_color(\"#ffffff\")\n    .selected_bg_color(\"#ee6c4d\")\n)\n\nApp(Frame(\"Employee Table\", 600, 400), table).run()\n```\n\nYou can see some other examples in [examples](examples) directory.\n\n## I18n Example\n\nAdd multi-language support to your app:\n\n```python\nfrom castella import App, Button, Column, Component, Text\nfrom castella.frame import Frame\nfrom castella.i18n import I18nManager, load_yaml_catalog\n\n# Load translations\nmanager = I18nManager()\nmanager.load_catalog(\"en\", load_yaml_catalog(\"locales/en.yaml\"))\nmanager.load_catalog(\"ja\", load_yaml_catalog(\"locales/ja.yaml\"))\nmanager.set_locale(\"en\")\n\n\nclass MyApp(Component):\n    def view(self):\n        return Column(\n            Text(manager.t(\"greeting\")),\n            Button(manager.t(\"button.save\")).on_click(self._save),\n            Button(\"日本語\").on_click(lambda _: manager.set_locale(\"ja\")),\n            Button(\"English\").on_click(lambda _: manager.set_locale(\"en\")),\n        )\n\n    def _save(self, _):\n        print(\"Saved!\")\n\n\nApp(Frame(\"I18n Demo\", 400, 300), MyApp()).run()\n```\n\n```yaml\n# locales/en.yaml\nlocale: en\ngreeting: \"Hello, World!\"\nbutton:\n  save: \"Save\"\n```\n\n```yaml\n# locales/ja.yaml\nlocale: ja\ngreeting: \"こんにちは！\"\nbutton:\n  save: \"保存\"\n```\n\n## Supported Platforms\nCurrently, Castella supports the following platforms:\n\n- Windows 10/11\n- Mac OS X\n- Linux\n- **iOS** (Simulator and Device)\n- Web browsers\n- Terminals\n\n### iOS Support\n\nCastella runs on iOS with full widget support including charts, data tables, and keyboard/IME input. Uses the castella-skia Metal backend for GPU-accelerated rendering.\n\n```bash\n# Build and run iOS demo (auto-downloads dependencies)\nAUTO_DOWNLOAD_DEPS=1 ./tools/build_ios.sh examples/ios_all_widgets_demo\n```\n\n**Building iOS dependencies locally:**\n\n```bash\n# Build pydantic-core for iOS\n./tools/build_pydantic_core_ios.sh\n\n# Build castella-skia for iOS\ncd bindings/python \u0026\u0026 ./build_ios.sh\n\n# Then build iOS app\n./tools/build_ios.sh examples/ios_all_widgets_demo\n```\n\nSee the [iOS Documentation](https://i2y.github.io/castella/ios/) for details.\n\n## castella-skia (Rust Backend)\n\nCastella uses a Rust-based Skia backend for GPU-accelerated rendering across all platforms:\n\n```\ncastella/\n├── castella-skia-core/    # Pure Rust core library (crates.io)\n└── bindings/\n    ├── python/            # Python bindings (PyPI: castella-skia)\n    ├── ruby/              # Ruby bindings (planned)\n    └── node/              # Node.js bindings (planned)\n```\n\nThe architecture separates the core rendering logic from language-specific bindings, enabling multi-language support.\n\n```bash\n# Build Python bindings\ncd bindings/python \u0026\u0026 maturin develop --release\n\n# Run Castella app\nuv run python examples/counter.py\n```\n\n## License\nMIT License\n\nCopyright (c) 2022 Yasushi Itoh\n\nPermission 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:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fi2y%2Fcastella","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fi2y%2Fcastella","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fi2y%2Fcastella/lists"}