Audion Python GUI Portable Template

Audion Python GUI Portable Template is a Windows-first template for packaging Python CLI projects as portable desktop tools.

It is meant for projects that already have useful command-line logic and now need a calm, repeatable GUI-shell around it.

What It Provides

• Embedded portable Python runtime in runtime\.
• Offline reinstall support through wheelhouse\.
• NiceGUI application layer in system_core\ui_nicegui\.
• pywebview desktop window launcher through launcher_gui.cmd.
• Resizable two-pane GUI: commands and parameters on the left, status and live terminal output on the right, with a draggable splitter.
• Compact parameter grids, subdued field borders, and wide searchable dropdowns.
• UX rules for complex forms: group related choices, use radio controls for small fixed choices, avoid duplicated run/favorite actions, and keep every action visibly tied to the object it changes.
• CMD/FZF project launchers for keyboard-driven workflows.
• Builder menu for runtime build, offline install, verification, license collection, and release archive creation.
• Optional portable PowerShell installer for native Windows picker dialogs and build helpers.
• GUI porting guidance for grouped choices, anchored actions, collapsible advanced fields, selected-model smoke status, replacing old manual model-list files in developed LLM projects, visual smoke screenshots, logs, reports, and smoke tests.

Design Principle

The GUI is a shell over the CLI, not a second implementation.

Keep project logic in Python modules and CLI commands. Let the GUI collect parameters, stage files, show progress, and mirror logs.

Canonical Workbench labels

The shared Workbench module uses the exact labels Source, Add file..., Target, Reset, Delete, and List. Its renderer and path-history engine live in system_core/ui_nicegui/workbench.py; project app.py files connect adapters and handlers without duplicating the module.

Main Entry Points

copybuilder_main.cmd
launcher_gui.cmd
launcher_project.cmd
launcher_tools.cmd

builder_main.cmd includes:

• build portable runtime;
• install portable PowerShell;
• install from local runtime and wheelhouse;
• verify portable environment;
• check/fix CMD encoding;
• update fzf;
• collect/prune/deduplicate licenses;
• make release archive.

Runtime Layout

copyruntime\                 embedded Python runtime
wheelhouse\              offline Python package cache
system_core\             project code and shared helpers
system_core\ui_nicegui\  GUI shell
system_core\powershell\  optional portable pwsh.exe
install\                 build, install, verify, release scripts
config\                  GUI and project config
input\                   default input folder
output\                  user-facing output
report\                  machine-readable reports and diagnostics
logs\                    runtime logs
release\                 release artifacts
licenses\                third-party notices

Portable PowerShell

PowerShell is not the business-logic engine. It is used for native Windows file/folder picker dialogs and some helper scripts.

Install it from:

copybuilder_main.cmd

Choose:

copy[04] POWERSHELL

The GUI picker lookup order is:

1. system_core\powershell\pwsh.exe
2. pwsh.exe from PATH
3. built-in powershell.exe

Quick Start

Build the portable runtime:

copybuilder_main.cmd

Verify the environment:

copyinstall\verify_portable_env.cmd

Run the GUI shell:

copylauncher_gui.cmd

What To Customize

• Replace system_core\main.py with the project entry point.
• Describe operations in the project manifest.
• Keep source paths, profile history, and GUI-only preferences in config\.
• Add project-specific file profiles and extension groups.
• Keep user results in output\; keep structured run metadata in report\.

Transport / Sync / Backup Engines

The template does not mandate rsync, rclone, Robocopy, or a custom engine.

Use the engine that fits the product:

• Python stdlib or project-specific Python code for audited, cross-platform logic.
• Robocopy for Windows-native high-volume copying.
• rclone when cloud remotes are first-class targets.
• rsync when Unix-like remote sync is the deployment reality.

The GUI-shell should wrap the chosen engine and make its plan, logs, dry-run, and result visible.

Documentation

Start with:

• README_TEMPLATE_RU.md
• README_GUI_TEMPLATE_RU.md
• docs\GUI_PORTING_GUIDE_RU.md
• install\README_GUI_PORTING.md
• install\README_INSTALL.md