Bears Workflows

# Colour Mixing Optimization

description: Iteratively mix RGB colours on an Opentrons OT-2 and minimize RMSE between the mixed colour and a target colour using real-time camera feedback and BO or LLM optimization.

## Required Skills

Invoke these skills before generating any commands:
- **puda-machines** → opentrons machine (liquid handling + `camera_capture`)
- **puda-protocol** → protocol generation and execution
- **puda-memory** → update `experiment.md` after every protocol creation and run
- **puda-report** → resolve the report **save path / output folder** only (the report filename and markdown layout are defined in this document)

## Required Machine

- **Opentrons OT-2** with camera attached (`machine_id: "opentrons"`)

## Core Principle 
The system must operate in a strict single-run, sequential execution loop.
At any time:
- Only **One active run** is allowed 
- Each iteration sues a **NEW run_id**
-No downstream step executres unless the run is **confirmed successful**

## Optimization Approaches

Ask the user which approach to use if not specified:

| Approach | When to use |
|---|---|
| **Bayesian Optimization (BO)** | Efficient for continuous volume ratios; fewer iterations to converge |
| **LLM** | Flexible reasoning; good when constraints or colour theory context matters |

See [optimization.md](optimization.md) for implementation details.

---

## Workflow

### Phase 0 — Run Lifecycle Safety

This applies to every iteration.

Mandatory Rules
-Never send play twice on same run
-Always poll until run reaches terminal state: successded, failed or stopped 

Hard Gate Condition

Proceed ONLY IF:
run.status == "succeeded"

Otherwise:
-STOP optimization loop
-Log failure
-Require recovery before continuing

### Phase 1 — Initialization

**Step 1 — Inputs (ask user before proceeding)**

Collect all of the following before starting. Do not proceed until every value is confirmed:

| Input | Description |
|---|---|
| Sample name | User-provided sample name to use in saved image filenames |
| Target colour source | Choose either `manual_rgb` or `measured_target_mix` |
| Target colour — if `manual_rgb` | `(R, G, B)` where each value is 0–255 |
| Target mix volumes — if `measured_target_mix` | One `(R_vol, G_vol, B_vol)` set in µL to dispense, capture, process, and use as the target RGB |
| Target mix volume well — if `measured_target_mix` | Mapping of the target mix volume set to the destination well, for example `(100, 100, 100) µL -> C1` |
| Target mix destination well — if `measured_target_mix` | Well used for the target-mix calibration run; this target well is not an optimization seed well |
| Total well volume | Total volume in µL per well (e.g. 300 µL) |
| **R dye source — deck slot** | OT-2 deck slot (`"1"`–`"11"`) for the labware holding **red** dye only |
| **G dye source — deck slot** | Deck slot for the labware holding **green** dye only |
| **B dye source — deck slot** | Deck slot for the labware holding **blue** dye only |
| `x_init` — 3 initial mixes | User-provided volume sets (see below) |
| `x_init` destination wells | Three user-selected destination wells, one for each `x_init` mix |
| Optimization approach | BO (EI or LCB) or LLM (choose model) |
| RMSE threshold | Stop when RMSE ≤ this value |
| Maximum iterations | Stop after this many iterations |

**Critical — RGB dye labware are three separate deck positions**

The R, G, and B dyes are loaded as **three independent `load_labware` calls** with **three separate `location` values**. You must **ask the user for each slot individually** (R, then G, then B — or present one form with three distinct fields). **Do not** ask a single question such as “which slot is the dye plate?” and reuse that answer for R, G, and B. **Do not** assume all th