Metadata-Version: 2.5
Name: caddforge-gui
Version: 0.7.0
Summary: FastAPI-based GUI server and web UI for CADDForge.
Author-email: Manuel Sellner <manuel.sellner@idorsia.com>, Christoph Sager <christoph.sager@idorsia.com>
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: caddforge-core>=0.24.0
Requires-Dist: fastapi>=0.110
Requires-Dist: pydantic>=2.5
Requires-Dist: python-multipart>=0.0.26
Requires-Dist: pyyaml>=6.0
Requires-Dist: uvicorn>=0.29
Description-Content-Type: text/markdown

# CADDForge GUI

Install this plugin with `python -m pip install caddforge-gui`. It depends directly
on `caddforge-core`; Python imports and CLI commands still use `caddforge`.
This release (0.7.0) requires `caddforge-core>=0.24.0`; GUI integrations use `caddforge-gui>=0.7.0`.
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)

```bash
cd caddforge-gui/frontend
npm install
npm run build
```

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

## Testing

Test the built wheel in a fresh environment with the dependencies used by release CI:

```bash
python -m pip install dist/*.whl pytest packaging httpx
python scripts/run_ci_tests.py
python -m pip check
```

Host tests use lightweight tool declarations and do not require scientific plugins.
Integration tests for actual GaMD and preparation declarations additionally run when
MD >=0.15.0 and, for preparation, docking >=0.8.0 are installed. Older or absent
plugins produce explicit skips for those integrations; a broken compatible plugin
still fails. This keeps GUI publication before the plugins that depend on it.

## Run

```bash
caddforge gui --host 0.0.0.0 --port 8000
```

## Scientific workbench

GUI 0.7.0 provides the scientific workbench with core 0.24.0 and the compatible
plugin versions in bundle 0.25.0. The approved design lives in `design/mockup`.

- Overview, searchable/paged Jobs, Tools and Settings use a common light/dark shell.
- Every exposed tool uses Inputs → Method → Compute → Review. Models supply actual
  defaults and complete configuration schemas. Auxiliary inputs and method fields
  are progressively disclosed; YAML/JSON import and YAML export use the same config.
- Local/Slurm controls, saved compute profiles, retained uploads, previous-job
  artifacts, browser drafts, validation and submission are owned by the host.
- Jobs keep Overview, Results, Logs, Configuration and Files together. Declared child
  tasks have their own paged view and aggregated, reconnecting log tails. Backend
  reconciliation runs once per server, with bounded work per polling cycle.
  Job details include **Delete job** for terminal workflows: keep files by default
  or explicitly remove owned job directories and completed child records.
  Active or uncertain execution blocks deletion.
- GNINA, UniDock and iDockYa publish an explicit pose manifest and share one Mol*
  viewer. Exact SDF record indices and corresponding flexible receptor states are
  required; ambiguous data is labelled rather than guessed. Original chemistry and
  coordinates remain intact. Mol* 5.11.0 is bundled locally and needs no CDN.
  Clicking a ligand shows its surrounding receptor residues. The viewer follows
  the GUI theme; dark mode is the default unless a light preference is saved.
- OpenBPMD retains its scalar results and analysis plots. RBFE adds the existing
  scientific network planner/editor as a specialized setup step. Reviewed networks
  are saved and retained with the job; unsaved changes block submission.

Implementation scope, validation results, remaining browser checks and local startup
are recorded in the [implementation notes](design/IMPLEMENTATION.md).

New tools should follow the [tool authoring contract](docs/plugin-gui-authoring.md).
Normal tools need metadata and existing artifact ports, with no tool-specific submit
form or backend panel. The [legacy extension runtime](docs/plugin-gui-legacy.md)
remains available for older third-party extensions.

### Frontend development

```bash
cd frontend
npm ci
npm test
npm run typecheck
npm run build
```

Built frontend assets and vendor licences ship in the Python package. Run the GUI
with `caddforge gui` or `caddforge-gui`; choose the registry/runs root through the
server's existing configuration or environment variables. The running GUI shares
canonical jobs and results with the CLI. Drafts and compute profiles remain browser
preferences, and an optional API token is stored only for the browser session.

Before merging, exercise a local and a Slurm job, an interrupted submission, log
reconnection, two rapidly selected poses, a missing receptor, a reviewed RBFE network,
and light/dark/narrow layouts in a real browser. Automated tests cover the core
contracts, REST routing/authentication, numeric pagination and shared form rendering.

## Third-party notices

The bundled React frontend and Mol* viewer retain their upstream MIT licences. Copyright and full
licence text ship in [static/THIRD_PARTY_LICENSES](src/caddforge_gui/static/THIRD_PARTY_LICENSES/NOTICE.txt)
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.

## Standard worker reporting

Workbench tools use common worker activity and canonical stage snapshots, including
PheSA, docking, OpenFE, plain MD, GaMD, structure preparation and trajectory analysis.
Measured work gets a current-stage percentage and ETA; opaque engine work shows its
stage, live output, heartbeat and an explicit unavailable ETA. Replica/edge/job counts
remain separate from scientific stage percentages. Heartbeats do not claim advancement.

Use the same registry as the GUI when inspecting work from the CLI:

```bash
caddforge logs JOB_ID
caddforge logs JOB_ID --follow
caddforge logs JOB_ID --registry-path /path/to/job_registry.sqlite --follow
```

The common source list includes `worker.log`, stdout/stderr, declared engine logs and
child jobs. Following a submitted campaign continues while children run and does not
execute scientific aggregation. Progress refresh is independent of backend status
changes. Stale snapshots lose their ETA, and cancellation does not leave replica/edge
units presented as live workers.

Runtime settings are `progress_update_interval_seconds: 5`,
`heartbeat_interval_seconds: 30` and `log_sync_interval_seconds: 30`; explicit existing
tool settings remain effective. Scratch data is synchronized resiliently and old
progress/activity/declared engine logs are retained with execution attempts. OpenFE
edges use the ordinary callable worker lifecycle and live log copy-back. Detailed
OpenFE iteration estimates are intentionally unavailable without validated counters.
