CADDForge GUI

Install this plugin with python -m pip install caddforge-gui. It depends directly on caddforge-core>=0.21.0; Python imports and CLI commands still use caddforge. For the complete public toolbox, including user-facing extras, install python -m pip install caddforge. When migrating an existing environment, uninstall the former caddforge core distribution before installing renamed core and updated plugins.

FastAPI server that hosts the CADDForge GUI and REST/SSE API.

Documentation

• Plugin GUI authoring guide:
  • docs/plugin-gui-authoring.md
• Shared plugin UI kit module:
  • src/caddforge_gui/static/assets/plugin_uikit.js
• Shared plugin backend helpers:
  • src/caddforge_gui/plugin_runtime.py

Development (frontend)

cd caddforge-gui/frontend
npm install
npm run build

This builds static assets into caddforge-gui/src/caddforge_gui/static.

Run

caddforge gui --host 0.0.0.0 --port 8000

Theme

• Default theme: light
• Toggle: top-bar Dark Mode / Light Mode button
• Persistence: saved in browser localStorage (caddforge-theme)

Plugin UI Kit

caddforge-gui provides a small reusable UI kit for plugin pages:

• Module: caddforge_gui/static/assets/plugin_uikit.js
• Runtime URL for extensions: /static/assets/plugin_uikit.js

Extension modules can import shared primitives (fields, sections, collapsibles, file pickers, etc.) via:

import { field, row, section, createFilePicker } from "../../assets/plugin_uikit.js";

Available higher-level helpers include:

• stepSection(stepNumber, title, note)
• modeSwitchSection(...)
• backendSection()
• submitBar(label)
• createPathOrFileInput(...)

For docking/pose analysis pages, there is also a reusable Mol* viewer panel:

• Module: caddforge_gui/static/assets/molstar_viewer.js
• Export: createDockingMolstarViewer({ title, description })
• Runtime URL for extensions: /static/assets/molstar_viewer.js

This keeps plugin GUIs visually consistent and avoids re-implementing common form/layout logic.

Plugin Backend Helpers

For extension backend routers (gui_extension.py), caddforge-gui also provides reusable helpers in caddforge_gui.plugin_runtime:

• encode_path_token / decode_path_token
• list_tool_jobs
• make_staging_dir
• store_upload (streamed upload writes)
• move_to_directory
• ensure_job_within_run_dir

For non-GUI/general runtime concerns (backend construction, backend submission, registry normalization), use caddforge.core.execution from caddforge-core.

Third-party notices

The bundled React frontend retains its upstream MIT licence. Copyright and full licence text ship in static/THIRD_PARTY_LICENSES in source distributions and wheels. Preserve these files when redistributing the frontend, and review them whenever frontend dependencies change.

Continuous integration and releases

.github/workflows/release.yml builds a wheel and source archive, validates metadata, and tests the installed wheel on Linux with Python 3.10 and 3.12. The lightweight test selection is recorded in scripts/ci_tests.json; external scientific engines are validated separately.

Pushing a matching v* release tag publishes the tested artifacts to PyPI. Branch pushes, pull requests and manual runs never publish. Configure a PyPI Trusted Publisher for the idorsia repository, release.yml workflow and pypi environment before pushing release tags. Runtime CADDForge dependencies must already be available publicly; publish core first, and publish docking/descriptors before MD.