# ClawLab – AI Lab Orchestrator

ClawLab is a reference AI orchestration application for high-throughput screening (HTS) and life-science laboratory workflows. It demonstrates a **scientist-in-the-loop** architecture in which an AI agent can coordinate experiment planning, simulated instrument execution, assay quality control, result analysis, and next-experiment recommendations—while the scientist remains the final decision authority.

The application is designed to integrate with **Intel SuperClaw** through the **Model Context Protocol (MCP)** and can optionally use **OpenVINO** for local AI inference.

> **Important:** ClawLab v1.0 is a synthetic/reference demonstration. It does **not** directly control real laboratory equipment.

## Architecture

```text
Scientist
    │
    ▼
Intel SuperClaw
    │
    │ MCP / Streamable HTTP
    ▼
ClawLab
 ┌───────────────────────────────────────────────┐
 │ Experiment Planning                            │
 │ Simulated HTS / Instrument Coordination       │
 │ Assay QC                                      │
 │ Candidate Hit Analysis                        │
 │ Next-Experiment Recommendation                │
 │ Scientist Approval Gate                       │
 └───────────────────────────────────────────────┘
```

## What the demo does

The default demo runs a synthetic HTS campaign and produces:

1. An experiment plan
2. Simulated plate/instrument execution
3. Assay QC metrics
4. Candidate hit analysis
5. An AI-assisted recommendation for the next experiment
6. A **scientist approval gate** before the recommendation is accepted

ClawLab exposes these capabilities through REST APIs and MCP tools.

## MCP tools

- `create_experiment_plan`
- `execute_simulated_hts`
- `get_assay_qc`
- `get_candidate_hits`
- `recommend_next_experiment`
- `get_campaign_state`

## Requirements

- Windows 10/11
- Python 3.12+ recommended
- PowerShell
- Internet access for initial package installation
- Optional: Intel hardware/driver support for OpenVINO
- Optional: Intel SuperClaw

Python 3.12 is recommended for predictable compatibility with the current Python AI/MCP stack.

## Quick start

### 1. Enter the repository

```powershell
cd C:\path\to\ClawLab-v1.0
```

### 2. Create and activate a virtual environment

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
```

If PowerShell blocks script execution:

```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1
```

### 3. Install dependencies

```powershell
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
```

### 4. Set the Python module path

```powershell
$env:PYTHONPATH=(Get-Location).Path
```

### 5. Start ClawLab

```powershell
python -m uvicorn backend.main:app --host 0.0.0.0 --port 8000
```

Open:

```text
http://127.0.0.1:8000
```

## Run the demo

Use the dashboard, or from another PowerShell window:

```powershell
Invoke-WebRequest -Method POST http://127.0.0.1:8000/api/demo/run
```

Check health:

```powershell
Invoke-WebRequest http://127.0.0.1:8000/api/health
```

Get campaign state:

```powershell
Invoke-WebRequest http://127.0.0.1:8000/api/state
```

Reset:

```powershell
Invoke-WebRequest -Method POST http://127.0.0.1:8000/api/demo/reset
```

## Scientist decision gate

After the synthetic campaign and recommendation are generated, ClawLab enters:

```text
AWAITING_SCIENTIST
```

Approve:

```powershell
Invoke-WebRequest -Method POST http://127.0.0.1:8000/api/decision/approve
```

Reject:

```powershell
Invoke-WebRequest -Method POST http://127.0.0.1:8000/api/decision/reject
```

The AI can analyze data and make recommendations, but the scientist remains the final decision authority.

## Connect to Intel SuperClaw

ClawLab exposes an MCP endpoint at:

```text
/mcp
```

When ClawLab runs on Windows and SuperClaw runs through its WSL2/Docker environment, configure the MCP server in:

**SuperClaw → Settings → Advanced → MCP**

Use:

```text
Name: ClawLab
Transport: HTTP / Streamable HTTP
Endpoint: http://host.docker.internal:8000/mcp
```

With WSL mirrored networking, `localhost`/`127.0.0.1` may also be usable.

After connecting, SuperClaw should discover the six ClawLab MCP tools.

Example end-to-end prompt:

```text
Run the ClawLab HTS demo for an EGFR inhibitor screen.
Analyze QC and candidate hits, recommend the next experiment,
and stop for scientist approval.
```

## OpenVINO local inference

The default provider is `mock`, so the demo runs without a downloaded AI model.

To use an OpenVINO-compatible local model:

```powershell
$env:CLAWLAB_AI_PROVIDER="openvino"
$env:CLAWLAB_OPENVINO_MODEL="C:\path\to\openvino-model"
$env:CLAWLAB_OPENVINO_DEVICE="CPU"
```

Then start the application normally:

```powershell
$env:PYTHONPATH=(Get-Location).Path
python -m uvicorn backend.main:app --host 0.0.0.0 --port 8000
```

For a supported Intel GPU/iGPU:

```powershell
$env:CLAWLAB_OPENVINO_DEVICE="GPU"
```

The model directory must be compatible with the `openvino_genai.LLMPipeline` interface used by the application.

## Run tests

From the repository root:

```powershell
$env:PYTHONPATH=(Get-Location).Path
pytest -q
```

The tests validate application health, demo execution, and the scientist approval workflow.

## REST API

| Endpoint | Method | Purpose |
|---|---|---|
| `/api/health` | GET | Application and AI-provider health |
| `/api/state` | GET | Current campaign state |
| `/api/demo/run` | POST | Run the synthetic HTS campaign |
| `/api/demo/reset` | POST | Reset campaign state |
| `/api/decision/approve` | POST | Approve the recommendation |
| `/api/decision/reject` | POST | Reject the recommendation |
| `/mcp` | MCP | Streamable HTTP MCP endpoint |

## Repository structure

```text
ClawLab-v1.0/
├── backend/
│   ├── main.py
│   ├── hts.py
│   ├── mcp_server.py
│   └── ai/
│       ├── provider.py
│       ├── mock_provider.py
│       └── openvino_provider.py
├── config/
│   └── config.yaml
├── docs/
│   ├── ARCHITECTURE.md
│   └── SUPERCLAW.md
├── scripts/
│   ├── run_demo.ps1
│   └── run_openvino.ps1
├── tests/
│   └── test_v1.py
├── ui/
│   └── index.html
├── requirements.txt
└── README.md
```

## Design principles

- **Scientist in the loop:** AI recommendations require human approval.
- **Tool-driven orchestration:** Laboratory capabilities are exposed as MCP tools.
- **Local-first AI:** OpenVINO can provide local inference where appropriate.
- **Modular integration:** The simulated instrument layer can later be replaced by real instrument adapters.
- **Auditable workflow:** Experiment state and workflow events are represented explicitly.
- **Reference architecture:** The project demonstrates an extensible pattern for AI-enabled laboratory automation.

## Current scope and limitations

ClawLab v1.0 currently uses synthetic HTS data, simulated instrument execution, synthetic assay QC/hit analysis, a mock AI provider by default, optional OpenVINO inference, and MCP integration with SuperClaw.

It does **not** currently provide:

- Direct control of production laboratory instruments
- LIMS/ELN integration
- GxP validation
- Production data persistence
- Production authentication/authorization
- Full audit/compliance controls
- Autonomous experimental execution without human approval

These capabilities can be added as the architecture evolves toward a production laboratory orchestration platform.

## License

TBD- repository's applicable license here.