Metadata-Version: 2.4
Name: clawcures-ui
Version: 0.8.1
Summary: Web control plane for ClawCures campaign orchestration and scientific execution.
Author-email: JJ Ben-Joseph <jj@tensorspace.ai>
License-Expression: MIT
Project-URL: Homepage, https://agentcures.com/
Project-URL: Repository, https://github.com/agentcures/clawcures-ui
Project-URL: Documentation, https://github.com/agentcures/clawcures-ui#readme
Project-URL: Issues, https://github.com/agentcures/clawcures-ui/issues
Keywords: drug discovery,refua,campaign,control plane,studio
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26.0
Requires-Dist: pandas>=2.2.2
Requires-Dist: scipy>=1.13.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: refua-mcp>=0.7.1
Requires-Dist: refua-clinical>=0.7.1
Requires-Dist: refua-data>=0.7.1
Requires-Dist: refua-preclinical>=0.7.1
Requires-Dist: refua-regulatory>=0.7.1
Requires-Dist: refua-wetlab>=0.7.1
Provides-Extra: dev
Requires-Dist: pre-commit>=4.5.1; extra == "dev"
Dynamic: license-file

# clawcures-ui

`clawcures-ui` is the ClawCures web control plane for planning and running discovery campaigns across the Refua workspace.

It provides:

- Mission control UI for planning (`plan`), execution (`run`), and autonomous loops (`run-autonomous` behavior)
- JSON plan editor with validation and direct execution
- Portfolio ranking UI for disease program prioritization
- Clinical trial management UI (trial CRUD, human/simulated enrollment, outcome capture, simulation refresh)
- Program graph command center (program registry, timeline events, stage-gate approvals/e-signature capture)
- Cross-package orchestration for `refua-data`, `refua-preclinical` (including CMC workflows), `refua-bench`, `refua-wetlab`, and `refua-regulatory`
- Dataset catalog and materialization controls with provenance extraction
- Benchmark gate execution against baselines for release decisions
- Wet-lab protocol validation/compile/run controls with lineage events
- Regulatory evidence bundle build/verify workflows from campaign jobs or direct payloads
- Animated telemetry widgets for running jobs, managed trials, patient counts, promising leads, and tools online
- Built-in objective/plan/portfolio templates loaded from workspace examples
- Ecosystem health panel with cross-product discovery metadata
- ClawCures-native handoff artifact generation and executable command suggestions
- Promising cures section with full ADMET property maps, assessments, and detailed therapeutic review cards
- Persistent background job history (SQLite)
- Job lifecycle operations (filter, cancel queued jobs, clear finished jobs)
- Runtime/tool introspection with graceful fallback when heavy ML deps are unavailable

This project is designed to reuse existing workspace components:

- `ClawCures` for planning, policy checks, orchestration, and portfolio ranking
- `refua-mcp` for tool execution when runtime dependencies are installed

## Install

```bash
cd path/to/clawcures-ui
python3.13 -m venv .venv
source .venv/bin/activate
pip install -e .
```

Use Python `>=3.11,<3.14`. Live execution depends on `refua-mcp`, which does not
support Python `3.14+`.

## Run

```bash
clawcures-ui --host 127.0.0.1 --port 8787 --open-browser
```

Or from source without install:

```bash
cd path/to/clawcures-ui
PYTHONPATH=src python -m clawcures_ui --host 127.0.0.1 --port 8787
```

Legacy compatibility is still shipped for existing automation:

- `refua-studio` remains as a console-script alias
- `python -m refua_studio` still works
- legacy `REFUA_STUDIO_*` auth token env vars are still accepted

## Podman

Build image:

```bash
cd path/to/clawcures-ui
podman build -t clawcures-ui:local -f Containerfile .
```

Run container:

```bash
podman run --rm -p 8787:8787 \
  -e REFUA_CAMPAIGN_OPENCLAW_BASE_URL=http://host.containers.internal:18789 \
  -v "$(pwd)/.clawcures-ui-data:/data" \
  -v "$(pwd)/..:/workspace:ro" \
  clawcures-ui:local
```

Notes:

- The container starts `clawcures-ui` on `0.0.0.0:8787`.
- Mount the monorepo root at `/workspace` so Studio can integrate with `ClawCures`, `refua-mcp`, and other sibling projects.
- Persistent job database lives in `.clawcures-ui-data/`.

## Podman Compose

From `clawcures-ui/`:

```bash
podman compose -f docker-compose.yml up --build
```

Then open `http://127.0.0.1:8787`.

## Configuration

Studio uses the same OpenClaw-related environment variables as `ClawCures`:

- `REFUA_CAMPAIGN_OPENCLAW_BASE_URL` (default: `http://127.0.0.1:18789`)
- `REFUA_CAMPAIGN_OPENCLAW_MODEL` (default: `openclaw:main`)
- `REFUA_CAMPAIGN_TIMEOUT_SECONDS` (default: `180`)
- `OPENCLAW_GATEWAY_TOKEN` or `REFUA_CAMPAIGN_OPENCLAW_TOKEN`

CLI flags:

- `--host`
- `--port`
- `--data-dir` (default: `.clawcures-ui`, with fallback to `.refua-studio` when present)
- `--workspace-root` (defaults to parent workspace)
- `--max-workers` (background job concurrency)

## API Endpoints

- `GET /api/health`
- `GET /api/config`
- `GET /api/tools`
- `GET /api/examples`
- `GET /api/ecosystem`
- `GET /api/command-center/capabilities`
- `GET /api/program-gates/templates`
- `GET /api/programs?limit=100&stage=lead_optimization`
- `GET /api/programs/{program_id}`
- `GET /api/programs/{program_id}/events?limit=200`
- `GET /api/programs/{program_id}/approvals?limit=200`
- `POST /api/programs/upsert`
- `POST /api/programs/sync-jobs`
- `POST /api/programs/{program_id}/events/add`
- `POST /api/programs/{program_id}/approve`
- `POST /api/programs/{program_id}/gate-evaluate`
- `GET /api/data/datasets?tag=admet&limit=60`
- `POST /api/data/materialize`
- `POST /api/bench/gate`
- `GET /api/wetlab/providers`
- `POST /api/wetlab/protocol/validate`
- `POST /api/wetlab/protocol/compile`
- `POST /api/wetlab/run`
- `GET /api/wetlab/lms` (resource index)
- `GET /api/wetlab/lms/*` (mirrors `refua-wetlab` LMS GET resources)
- `POST /api/wetlab/lms/*` (mirrors `refua-wetlab` LMS POST resources)
- `GET /api/regulatory/bundles?limit=100`
- `POST /api/regulatory/bundle/build`
- `POST /api/regulatory/bundle/verify`
- `GET /api/drug-portfolio?min_score=50&limit=60`
- `GET /api/promising-cures?min_score=50&limit=60`
- `GET /api/clinical/trials`
- `GET /api/clinical/trials/{trial_id}`
- `GET /api/clinical/trials/{trial_id}/sites`
- `GET /api/clinical/trials/{trial_id}/ops`
- `GET /api/preclinical/templates`
- `GET /api/preclinical/cmc/templates`
- `GET /api/jobs?limit=80&status=running,failed`
- `GET /api/jobs/{job_id}`
- `POST /api/jobs/{job_id}/cancel`
- `POST /api/jobs/clear`
- `POST /api/plan`
- `POST /api/run`
- `POST /api/plan/validate`
- `POST /api/plan/execute`
- `POST /api/portfolio/rank`
- `POST /api/clawcures/handoff`
- `POST /api/clinical/trials/add`
- `POST /api/clinical/trials/update`
- `POST /api/clinical/trials/remove`
- `POST /api/clinical/trials/enroll`
- `POST /api/clinical/trials/enroll-simulated`
- `POST /api/clinical/trials/result`
- `POST /api/clinical/trials/simulate`
- `POST /api/clinical/trials/site/upsert`
- `POST /api/clinical/trials/screen`
- `POST /api/clinical/trials/monitoring/visit`
- `POST /api/clinical/trials/query/add`
- `POST /api/clinical/trials/query/update`
- `POST /api/clinical/trials/deviation/add`
- `POST /api/clinical/trials/safety/add`
- `POST /api/clinical/trials/milestone/upsert`
- `POST /api/preclinical/plan`
- `POST /api/preclinical/schedule`
- `POST /api/preclinical/bioanalysis`
- `POST /api/preclinical/workup`
- `POST /api/preclinical/cmc/plan`
- `POST /api/preclinical/cmc/batch-record`
- `POST /api/preclinical/cmc/stability-plan`
- `POST /api/preclinical/cmc/stability-assess`
- `POST /api/preclinical/cmc/release-assess`

### `POST /api/run` payload

```json
{
  "objective": "Design an initial campaign against KRAS G12D",
  "system_prompt": null,
  "dry_run": false,
  "async_mode": true,
  "autonomous": false,
  "max_rounds": 3,
  "max_calls": 10,
  "allow_skip_validate_first": false,
  "plan": null
}
```

### `POST /api/clawcures/handoff` payload

```json
{
  "objective": "Design an initial campaign against KRAS G12D",
  "system_prompt": null,
  "plan": {"calls": []},
  "autonomous": false,
  "dry_run": true,
  "max_calls": 10,
  "allow_skip_validate_first": false,
  "write_file": true,
  "artifact_name": "kras_handoff.json"
}
```

Returns a normalized handoff artifact plus ready-to-run `ClawCures` CLI commands.

### `POST /api/clinical/trials/add` payload

```json
{
  "trial_id": "studio-clinical-demo",
  "status": "planned",
  "config": null
}
```

### `POST /api/clinical/trials/enroll` payload

```json
{
  "trial_id": "studio-clinical-demo",
  "patient_id": "human-001",
  "source": "human",
  "arm_id": "control",
  "demographics": {"age": 62, "weight": 76},
  "baseline": {"endpoint_value": 48.1},
  "metadata": {"site_id": "site-01"}
}
```

### `POST /api/clinical/trials/simulate` payload

```json
{
  "trial_id": "studio-clinical-demo",
  "replicates": 8,
  "seed": 7,
  "async_mode": true
}
```

## Background Jobs

Jobs are persisted in SQLite at:

- `<data-dir>/studio.db`

Each job records request payload, status transitions (`queued` -> `running` -> `completed`/`failed`), result JSON, and error text.
`cancelled` is also tracked when queued jobs are cancelled before execution.

## Runtime Behavior

- If `refua-mcp` runtime dependencies are available, Studio executes plans through `RefuaMcpAdapter`.
- If unavailable, Studio falls back to a static tool list for planning/validation and emits warnings.
- Dry-run workflows and policy validation remain usable even without heavy runtime dependencies.
- Clinical trial endpoints require the scientific stack shipped in package dependencies (`numpy`, `pandas`, `scipy`, `pyyaml`).
- Command-center integrations require workspace access to sibling repos for bridge imports:
  `refua-data`, `refua-preclinical`, `refua-bench`, `refua-regulatory`, and `refua-wetlab`.

## Tests

```bash
cd path/to/clawcures-ui
python -m unittest discover -s tests -v
```

Playwright E2E suite:

```bash
cd path/to/clawcures-ui
npm install
npx playwright install chromium
npm run test:e2e
```

The E2E runner boots a real Studio server via `.venv_release` on an isolated
`.playwright-data/` directory and exercises mission-control workflows across
command center, planning/jobs, clinical operations, and wet-lab/regulatory flows.
Create `.venv_release` with Python `3.11`-`3.13`, not `3.14+`.

## Build

```bash
cd path/to/clawcures-ui
python -m build
```

Build artifacts are written to `dist/` (`.tar.gz` and `.whl`).

## Project Layout

```text
clawcures-ui/
  Containerfile
  docker-compose.yml
  src/clawcures_ui/
    app.py
    bridge.py
    cli.py
    config.py
    runner.py
    storage.py
    static/
      index.html
      app.js
      styles.css
  src/refua_studio/
    ...
  tests/
```

## Notes

- The Studio UI is a static single-page app served by the Python server.
- No third-party web framework is required.
- Studio now includes scientific dependencies to support embedded clinical operations alongside campaign orchestration.
