refua-studio 0.6.0

Web control plane for Refua campaign orchestration and scientific execution.

refua-studio

refua-studio is the Refua web control plane for planning and running discovery campaigns.

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
• Built-in objective/plan/portfolio templates loaded from workspace examples
• Promising drug portfolio section with candidate cards, scores, metrics, and full detail view
• 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

cd path/to/refua-studio
pip install -e .

Run

refua-studio --host 127.0.0.1 --port 8787 --open-browser

Or from source without install:

cd path/to/refua-studio
PYTHONPATH=src python -m refua_studio --host 127.0.0.1 --port 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: .refua-studio)
• --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/drug-portfolio?min_score=50&limit=60
• 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/run payload

{
  "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
}

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.

Tests

cd path/to/refua-studio
python -m unittest discover -s tests -v

Project Layout

refua-studio/
  src/refua_studio/
    app.py
    bridge.py
    cli.py
    config.py
    runner.py
    storage.py
    static/
      index.html
      app.js
      styles.css
  tests/

Notes

• The Studio UI is a static single-page app served by the Python server.
• No third-party web framework is required.
• This keeps installation lightweight while still integrating with the existing Refua ecosystem.