Turn a plain-language learning idea into a real, installable Sugar activity.
One clickable file — GTK, PyGObject, and the Sugar toolkit bundled in. Works on a modern x86_64 Linux desktop with nothing installed. See Portable AppImage.
Features · Requirements · Setup · Usage · Development
Sugar Activity Studio is a standalone desktop application for Activity on Demand by Sugar Labs.
It helps learners and teachers describe an activity in plain words and turn that idea into a complete Sugar activity. The studio plans, generates, validates, previews, refines, and packages the activity as an installable .xo bundle.
Example:
“A fraction matching game with levels and instant feedback.”
The studio runs on any Linux desktop and does not require the Sugar shell to be installed or running. When Sugar is installed, the studio is itself a Sugar activity, so it can be launched from the activity ring like any other activity — see Run from the Sugar activity ring.
idea → enhance → plan → generate → validate → run → preview → refine → export
The studio opens with a Sugar-inspired home view centered around your XO identity. Generated activities are arranged around it using the same ring-style geometry as the Sugar shell.
You can open an activity, continue modifying it, or create a new one from the home screen.
Choose a learning area, describe your idea, and send it to the studio.
The prompt enhancement flow can expand short or rough ideas into a clearer activity brief. The enhanced brief is shown back to you, helping you understand what the model will build and how to write stronger prompts.
The generation pipeline retrieves patterns from real installed Sugar activities using local RAG. It uses those patterns to plan and generate the activity while staying close to Sugar conventions.
No activity data is uploaded for training.
Generated code is not accepted only because it looks correct. Each candidate is validated for syntax, Sugar API usage, import safety, and request alignment.
When GTK runtime infrastructure is available, the activity is run in a separate, minimal-environment subprocess, event-pumped, saved, restored, and checked before it is accepted; otherwise the plan explicitly records that runtime verification remains unavailable. The complete file is generated only once. Failures enter a transactional debugging loop that applies focused SEARCH/REPLACE repairs to that same source, rolls back bad patches, and re-runs every acceptance gate. It never discards a failed candidate for full regeneration.
Generated activities run directly inside the studio preview.
You can click part of the preview and describe a change. Refinements are applied as minimal patches, with full version history preserved.
The studio lets you inspect the generated code, review the plan, and move between revisions. This makes the process transparent and easier to debug.
Activities can be exported as .xo bundles, exported as buildable Flatpak sources, or installed directly to ~/Activities.
Installed activities can be launched immediately using sugar-activity3.
Generated code is checked against an import and call allowlist. Network access and unsafe filesystem APIs are blocked, and failure paths are designed to degrade gracefully.
The GTK and Sugar dependencies come from your Linux distribution, not PyPI.
| Requirement | Purpose |
|---|---|
| Python 3.8 or newer | Runs the studio |
| GTK 3 + PyGObject | Provides the desktop UI |
| Sugar Toolkit GTK3 | Sugar widgets, .xo packaging, and sugar-activity3 launcher |
| sugar-artwork themes | Optional Sugar visual styling |
On Debian or Ubuntu:
sudo apt install python3-gi gir1.2-gtk-3.0 python3-sugar3 sugar-toolkit-gtk3The studio depends on the Sugar toolkit as a library, the same way a GTK app depends on GTK. It does not require the Sugar desktop shell.
git clone https://github.com/Ashutoshx7/Sugar-activity-on-Demand.git
cd Sugar-activity-on-Demand
python3 bin/sugar-aod-studioOr run:
python3 main.pyOptionally, install the launcher for your user — sugar-aod-studio
then works from any directory and the studio appears in your app menu:
./install.sh # ./install.sh --uninstall to remove
sugar-aod-studioThe app keeps running from the checkout (git pull is the upgrade
path); pip install is intentionally not supported because the GTK
and Sugar toolkit dependencies come from your distribution, not PyPI.
The studio is also a Sugar activity, so it can be launched from the activity ring like any other activity — no terminal needed:
./install.sh --ring # ./install.sh --uninstall to removeThis runs python3 setup.py dev, which symlinks this checkout into
~/Activities/SugarActivityStudio.activity. Open the Sugar shell and
Sugar Activity Studio appears in the ring; the shell launches it via
sugar-activity3 activity.StudioActivity. To build a distributable
bundle instead, run python3 setup.py dist_xo (produces
dist/SugarActivityStudio-1.xo).
Note: activities you generate from inside the studio still open in a separate
sugar-activity3window rather than as fully ring-integrated activities — that integration is planned separately.
To get a single file you can double-click to launch the studio — with GTK, PyGObject, and the Sugar toolkit all bundled, so nothing needs to be installed on the target machine — build an AppImage:
./packaging/appimage/build-appimage.shIt produces dist/Sugar_Activity_Studio-x86_64.AppImage (~54 MB). Mark it
executable and double-click, or run it directly:
chmod +x dist/Sugar_Activity_Studio-x86_64.AppImage
./dist/Sugar_Activity_Studio-x86_64.AppImageThe build downloads linuxdeploy, its GTK plugin, and appimagetool on
first run (cached under packaging/appimage/tools/).
Caveats: the AppImage is built against the host's glibc, so it runs on modern desktops (roughly Ubuntu 24.04 / Debian 13 and newer); for older distributions, build it inside an older base image. Double-click needs FUSE — otherwise run with
--appimage-extract-and-run.
Open the create page and use the provider selector next to the prompt box.
Choose a provider, paste your API key, and save. Keys are stored locally in your profile and are only used to call the provider you select.
| Option | Details |
|---|---|
| Providers | OpenRouter, Gemini, OpenAI, Claude, DeepSeek, Qwen, Moonshot, Ollama |
| Default | OpenRouter with google/gemini-3.5-flash |
| Offline mode | Keyless local template mode for trying the flow without an AI provider |
| Overrides | AOD_OPENROUTER_MODEL, AOD_GEMINI_MODEL, AOD_OLLAMA_MODEL, and AOD_LLM_PROVIDER |
View all activities you have created around your XO icon. Open an activity, modify an existing one, or create a new project.
Pick a learning area and describe your idea. Use prompt enhancement to turn a rough idea into a more complete activity brief, or send the prompt directly.
Short prompts can be enhanced automatically using the auto-enhance toggle.
Watch the generation pipeline progress, then explore the generated activity through the preview, review, and version tabs.
You can refine the activity by selecting part of the preview or sending a follow-up instruction.
Export the activity as an .xo bundle, export Flatpak sources, or install it directly to ~/Activities.
| Path | Contents |
|---|---|
~/.sugar/default/aod/ |
Projects, sessions, jobs, and locally stored API keys |
~/Activities/ |
Installed Sugar activities you generate |
~/Activities/SugarActivityStudio.activity |
The studio itself, once registered in the ring (./install.sh --ring) — a symlink back to this checkout |
The ~/.sugar/default/aod/ directory is shared with a Sugar shell install when one is available.
Run the test suite:
python3 -m pytest tests/ -qRun linting:
python3 -m flake8 core llm generation service exports preview ui main.pyThe codebase is organized by domain:
| Directory | Purpose |
|---|---|
core/ |
Specs, licenses, and project models |
llm/ |
Providers, credentials, and prompt enhancement |
generation/ |
Pipeline, RAG, code generation, repair, validation, and refinement |
service/ |
Job queue and sessions |
exports/ |
Flatpak and export logic |
preview/ |
Activity preview runtime |
ui/ |
GTK interface |
activity.py, activity/, setup.py |
Sugar activity bundle: the StudioActivity entry class, activity.info, icon, and the bundlebuilder script |
The studio has two entry points that share the same CreateAIActivityPanel UI: main.py (standalone desktop window, via bin/sugar-aod-studio) and activity.py (StudioActivity, launched by sugar-activity3 from the ring). Both depend only on the Sugar toolkit — never the shell (jarabe); tests/test_studio.py and tests/test_activity_bundle.py enforce that.
The complete contributor documentation is available in the Fumadocs site
under website/. Start it with:
cd website
npm install
npm run devThen open http://localhost:3000/docs. The source pages cover setup, the user workflow, architecture, generation and repair, providers, persistence, security, exports, testing, troubleshooting, and contribution conventions. The earlier concise architecture map remains at docs/ARCHITECTURE.md.
A test ensures that no jarabe module from the Sugar shell is imported, keeping the studio independent from the full Sugar desktop environment.
Sugar Activity Studio was extracted from the aod-activity-on-demand branch of the Sugar shell fork, where the same experience also runs embedded inside the Sugar home view.
The home ring layout is ported from Sugar's favoriteslayout.py.
GPL-3.0-or-later, same as Sugar. See LICENSE.