Metadata-Version: 2.4
Name: ClawCures
Version: 0.7.2
Summary: Campaign orchestration layer built on OpenClaw planning and refua-mcp 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/refua
Project-URL: Documentation, https://github.com/agentcures/refua#readme
Project-URL: Issues, https://github.com/agentcures/refua/issues
Keywords: drug discovery,machine learning,orchestration,planning,mcp,refua
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
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 :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: refua-mcp>=0.7.1
Requires-Dist: refua-clinical>=0.7.1
Provides-Extra: dev
Requires-Dist: pre-commit>=4.5.1; extra == "dev"
Dynamic: license-file

# ClawCures

Disease-campaign orchestration that separates planning from execution:
- OpenClaw plans through `/v1/responses`.
- `refua-mcp` executes typed scientific tools, with built-in `web_search`/`web_fetch` for evidence collection.

## What You Get

- Single-run planner/executor flow.
- Autonomous planner/critic loop with policy checks.
- Offline plan validation and dry-run modes.
- Portfolio ranking for disease-program prioritization.
- Structured `promising_cures` output with full ADMET property maps and assessment text.

## Requirements

- Python `>=3.11,<3.14` (Python `3.14+` is not supported by `refua-mcp`).
- A running OpenClaw Gateway if you want live planning.
- Optional: `refua-mcp` runtime dependencies for tool execution.

## Quick Start

1. Install

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

2. Configure OpenClaw access
- Set your gateway URL with `REFUA_CAMPAIGN_OPENCLAW_BASE_URL`.
- Ensure OpenClaw `responses` endpoint is enabled.
- Provide auth with one of:
  - `REFUA_CAMPAIGN_OPENCLAW_TOKEN`
  - `OPENCLAW_GATEWAY_TOKEN`
  - `OPENCLAW_GATEWAY_PASSWORD` (for password mode)

3. Run an offline smoke test (no OpenClaw call)

```bash
ClawCures run \
  --objective "Offline validation" \
  --plan-file examples/plan_template.json \
  --dry-run
```

4. Simplest live invocation (all-disease cure mission)

```bash
ClawCures run
```

`ClawCures run` now loops continuously by default (`--max-cycles 0`) until you stop it.
To run a single cycle and exit, use `--max-cycles 1`.
In loop mode, memory is preserved automatically by reusing a stable session key, enabling OpenClaw response storage, and carrying concise cycle summaries forward into subsequent planning objectives.

By default, `ClawCures run` sets the objective to:
"Find cures for all diseases by prioritizing the highest-burden conditions and researching the best drug design strategies for each."

If planner JSON generation fails repeatedly (common on small local models), ClawCures now auto-attempts repair passes and then falls back to a deterministic all-disease bootstrap validation plan.
For all-disease objectives, this fallback now includes deterministic `web_search` target-discovery queries before validation calls.

5. Run a live planning dry-run

```bash
ClawCures run \
  --dry-run
```

## Environment Variables

| Variable | Default | Purpose |
|---|---|---|
| `REFUA_CAMPAIGN_OPENCLAW_BASE_URL` | `http://127.0.0.1:18789` | OpenClaw Gateway base URL |
| `REFUA_CAMPAIGN_OPENCLAW_MODEL` | `openclaw:main` | OpenClaw model/agent ID |
| `REFUA_CAMPAIGN_TIMEOUT_SECONDS` | `180` | API timeout |
| `REFUA_CAMPAIGN_OPENCLAW_TOKEN` | unset | Bearer token override |
| `OPENCLAW_GATEWAY_TOKEN` | unset | Gateway token fallback |
| `OPENCLAW_GATEWAY_PASSWORD` | unset | Password-mode fallback token |
| `REFUA_CAMPAIGN_SESSION_KEY` | unset | Optional stable OpenClaw `user` key for cross-turn memory |
| `REFUA_CAMPAIGN_STORE_RESPONSES` | unset | Optional bool (`true/false`) for OpenClaw response storage |
| `REFUA_CAMPAIGN_AGENT_MODEL_MAP_JSON` | unset | Optional JSON object for phase/domain model routing (e.g. `{"planner:oncology":"openclaw:oncology-planner","critic":"openclaw:critic"}`) |
| `BRAVE_API_KEY` | unset | Optional key for higher-quality `web_search` results |
| `CLAWCURES_ALLOW_PRIVATE_WEB_FETCH` | unset | Set `true` to allow `web_fetch` against localhost/private IPs |

## CLI Commands

| Command | What it does |
|---|---|
| `ClawCures print-default-prompt` | Print bundled mission prompt |
| `ClawCures list-tools` | Show available execution tools (`refua-mcp` + web tools) |
| `ClawCures run ...` | Continuous planner + execution loop (`--max-cycles 0` default) |
| `ClawCures run-autonomous ...` | Planner/critic multi-round loop |
| `ClawCures validate-plan ...` | Policy-check a local JSON plan |
| `ClawCures rank-portfolio ...` | Rank disease programs from JSON input |

## Common Usage

Run one plan + execute cycle:

```bash
ClawCures run \
  --max-cycles 1 \
  --output artifacts/kras_campaign_run.json
```

Run with OpenClaw native function calling (no intermediate JSON plan parsing):

```bash
ClawCures run \
  --max-cycles 1 \
  --native-tool-loop \
  --session-key mission-all-disease-v1 \
  --store-responses \
  --stream \
  --native-discovery-bootstrap-rounds 2 \
  --auto-web-fetch \
  --agent-model-map-json '{"planner:oncology":"openclaw:oncology-planner","critic":"openclaw:critic"}' \
  --evidence-file docs/RESEARCH.md \
  --output artifacts/native_tool_loop_run.json
```

The run JSON now includes:
- `promising_cures`: ranked therapeutic candidates extracted from tool outputs
- `promising_cures_summary`: aggregate counts and ADMET coverage
- `interesting_targets`: web-derived disease target hypotheses ranked by evidence density
- `interesting_targets_summary`: aggregate counts and top target list

Each cure includes:
- `metrics` (binding/admet/affinity/potency signals)
- `admet.key_metrics` (`admet_score`, `safety_score`, `adme_score`, `rdkit_score` when available)
- `admet.properties` (full ADMET scalar property map from discovered outputs)
- `assessment` (risk/opportunity summary)

Offline autonomous policy check:

```bash
ClawCures run-autonomous \
  --objective "Offline policy check" \
  --plan-file examples/plan_template.json \
  --dry-run
```

Rank programs:

```bash
ClawCures rank-portfolio \
  --input examples/portfolio_input.json
```

## Release Packaging

Build and validate release artifacts in a version-specific directory:

```bash
./scripts/build_release_artifacts.sh
```

Upload only from that release directory (not from `dist/*`):

```bash
python -m twine upload dist/release-<version>/*
```

## OpenClaw Compatibility

Verified against official OpenClaw docs and latest stable release `v2026.2.15` (released 2026-02-16):
- API interface: `POST /v1/responses`
- Request fields used by this project: `model`, `input`, `instructions`
- Auth model: `Authorization: Bearer ...` token/password
- Endpoint behavior note: OpenClaw currently ignores `metadata` for prompt construction, so this project does not rely on metadata for critic payloads

Primary references:
- https://docs.openclaw.ai/openapi/openapi/responses_api/
- https://docs.openclaw.ai/openclaw/faq/
- https://github.com/openclaw/openclaw/releases/tag/v2026.2.15

## Troubleshooting

- `connection refused` to `/v1/responses`
  - OpenClaw Gateway is not running or `REFUA_CAMPAIGN_OPENCLAW_BASE_URL` is wrong.
- `401` or auth errors
  - Token/password env var is missing or mismatched with gateway auth mode.
- `requires a different Python: ... not in '<3.14,>=3.11'`
  - Use Python `3.11`, `3.12`, or `3.13`.

## Notes

- Tool plans are strict JSON for reproducibility.
- All tool calls go through a strict allowlist.
- `web_search` and `web_fetch` are included in the allowlist for target/evidence discovery.
- `web_fetch` blocks localhost/private-network targets by default for safety.
- `--native-tool-loop` uses OpenClaw function calls directly, executing tools turn-by-turn.
- `--session-key` + `--store-responses` wire OpenClaw session memory across campaign turns.
- `--stream` requests OpenClaw streaming responses; `--stream-to-stderr` mirrors streamed deltas to stderr.
- `--agent-model-map-file/--agent-model-map-json` enable disease/phase agent routing.
- `--evidence-file` injects local literature text into OpenClaw input for evidence-grounded planning.
- `--native-discovery-bootstrap-rounds` forces early native-loop rounds to web discovery tools only (`web_search`, `web_fetch`).
- `--auto-web-fetch` follows discovered web_search URLs with bounded web_fetch calls for richer target evidence.
- `--native-tool-fail-fast` disables recoverable tool-error feedback and fails immediately on tool exceptions.
- Mission framing is aspirational; never claim cures without evidence.
- For local-model reliability, planner output is auto-repaired and canonicalized (`args`/tool aliases) before execution.
- `ClawCures run` defaults to an infinite loop. Use `--max-cycles 1` for a single cycle.
- Loop mode carries forward compact cross-cycle memory (prior findings, failures, and state hints) to reduce repeated work.
- Architecture details: `docs/ARCHITECTURE.md`
- Research notes: `docs/RESEARCH.md`
