Pylabrobot

PyLabRobot

Use PyLabRobot's hardware-agnostic frontends, resource tree, trackers, and

device-specific backends to develop laboratory automation. Default to local

manifest validation, bookkeeping, and the software-only chatterbox backend.

Verified snapshot

• PyPI stable: PyLabRobot==0.2.1, released 2026-03-23.
• Upstream requirement: Python >=3.9. This skill uses Python 3.11 for its

reproducible smoke tests.

• /stable/ documentation identifies itself as 0.2.1. /dev/ and repository

main describe unreleased work and must not be assumed available in 0.2.1.

• Stable liquid-handler backends include STARBackend, VantageBackend,

EVOBackend, OpentronsOT2Backend, and the offline

LiquidHandlerChatterboxBackend.

• PyLabRobot's GitHub Releases page has no 0.2.x software release entry; use

the PyPI history, v0.2.1 tag, and changelog as release evidence.

Non-negotiable hardware boundary

Never connect to, initialize, home, move, heat, shake, spin, pump, open/close,

or otherwise command physical equipment automatically. Do not turn a simulation

plan into a live backend merely by changing an environment variable, config

value, or import.

Before any separately authorized live run, require a trained human to:

• Explicitly confirm the exact backend, device identity, firmware, transport,

deck, and protocol revision.

• Reconcile the physical deck against the resource tree, including carriers,

adapters, lids, plates, tip racks, waste, labware orientation, barcodes, and

every occupied coordinate.

• Verify calibration, teaching, motion envelopes, collision risks, gripper or

channel clearances, and all aspiration/dispense coordinates.

• Review source identity and actual fill volume, dead volume, destination

capacity, tip type/capacity/filter compatibility, channel mapping, units,

heights, rates, liquid class, blowout/mixing, and contamination boundaries.

• Confirm guards, doors, waste capacity, containment, emergency stop readiness,

PPE, biosafety/chemical controls, and a safe abort/recovery procedure.

• Approve a slow dry run or nonhazardous commissioning run when anything is

new or changed.

Tracker state is bookkeeping, not sensing. It cannot prove that liquid or a

tip is physically present. The Visualizer renders resource/tracker events; it

does not model physics. Chatterbox prints planned operations; it does not prove

calibration, reachability, collision freedom, liquid behavior, or device state.

Required intake

Do not guess any of these:

• Exact device model, installed options, firmware, computer/OS, and transport.
• Stable PyLabRobot version and required extras.
• Deck/deck origin, carriers, adapters, resource definitions, dimensions,

coordinates, orientations, and motion clearances.

• Plate/tube/reservoir capacities and dead volumes; initial physical volumes.
• Tip model, filter, fitting, capacity, rack state, channel count, and channel

mapping.

• Transfer units (uL, mm, uL/s, s), heights, rates, mixing, air gaps,

blowout, liquid properties, and validated vendor liquid class.

• Contamination policy, controls, waste handling, operator interventions,

acceptance criteria, and recovery procedure.

If information is missing, produce an assumptions/blockers list and an offline

draft only.

Reproducible install

For offline API inspection and chatterbox simulation:

uv venv --python 3.11 .venv-pylabrobot
uv pip install --python .venv-pylabrobot/bin/python "PyLabRobot==0.2.1"

On Windows, use .venv-pylabrobot\Scripts\python.exe. Do not install hardware

extras until the user names the device and explicitly approves its transport

dependencies. Then inspect the matching stable device page before considering a

pin such as "PyLabRobot[serial]==0.2.1" or "PyLabRobot[usb]==0.2.1".

Offline-first workflow

Run from the repository root. Every bundled CLI uses strict, bounded UTF-8

JSON/CSV, local non-symlink paths, fixed allowlists, and JSON output. None can

select a live backend.

python3 skills/pylabrobot/scripts/validate_manifest.py \
  --input tests/pylabrobot/fixtures/protocol_manifest.json

python3 skills/pylabrobot/scripts/check_deck_geometry.py \
  --input tests/pylabrobot/fixtures/protocol_manifest.json

python3 skills/pylabrobot/scripts/plan_transfers.py \
  --manifest tests/pylabrobot/fixtures/protocol_manifest.json \
  --transfers tests/pylabrobot/fixtures/transfers.csv

python3 skills/pylabrobot/scripts/generate_simulation_plan.py \
  --manifest tests/pylabrobot/fixtures/protocol_manifest.json \
  --transfers tests/pylabrobot/fixtures/transfers.csv

python3 skills/pylabrobot/scripts/inspect_backends.py \
  --expected-version 0.2.1 --strict

The geometry checker uses conservative static axis-aligned boxes; it is not a

motion planner. The transfer planner requires one new tip per row and checks

source/dead/destination volumes, tip capacity, wells, channels, heights, rates,

units, and allowlists. Review

assets/protocol-manifest.schema.json and the synthetic fixtures before making

a project-specific manifest.

Verified software-only example

The exact backend below is software-only. Do not substitute a hardware backend.

from pylabrobot.liquid_handling import LiquidHandler
from pylabrobot.liquid_handling.backends import LiquidHandlerChatterboxBackend
from pylabrobot.resources import (
    Cor_96_wellplate_360ul_Fb,
    PLT_CAR_L5AC_A00,
    TIP_CAR_480_A00,
    hamilton_96_tiprack_1000uL_filter,
    set_tip_tracking,
    set_volume_tracking,
)
from pylabrobot.resources.hamilton import STARLetDeck

set_tip_tracking(True)
set_volume_tracking(True)

deck = STARLetDeck()
tip_carrier = TIP_CAR_480_A00(name="tip_carrier")
tips = hamilton_96_tiprack_1000uL_filter(name="tips")
tip_carrier[0] = tips
plate_carrier = PLT_CAR_L5AC_A00(name="plate_carrier")
source = Cor_96_wellplate_360ul_Fb(name="source")
destination = Cor_96_wellplate_360ul_Fb(name="destination")
plate_carrier[0] = source
plate_carrier[1] = destination
deck.assign_child_resource(tip_carrier, rails=3)
deck.assign_child_resource(plate_carrier, rails=15)
source.get_well("A1").tracker.set_volume(100.0)  # planned state, not sensing

lh = LiquidHandler(backend=LiquidHandlerChatterboxBackend(), deck=deck)
await lh.setup()  # safe here only because the backend above is software-only
try:
    await lh.pick_up_tips(tips["A1"])
    await lh.aspirate(source["A1"], vols=[10.0])
    await lh.dispense(destination["A1"], vols=[10.0])
    await lh.return_tips()
finally:
    await lh.stop()

API rules that prevent stale code

• Current names are STARBackend, VantageBackend, EVOBackend, and

OpentronsOT2Backend; do not use stale STAR, TecanBackend,

OpentronsBackend, or ChatterboxBackend imports.

• Use LiquidHandlerChatterboxBackend for generic offline liquid-handler

testing. ChatterBoxBackend is a separate legacy-named export; do not

conflate the two.

• Visualizer(resource=...) is valid, followed by await vis.setup() and

await vis.stop(); it starts localhost HTTP/WebSocket servers and may open a

browser.

• There is no generic from pylabrobot.liquid_handling import LiquidClass in

0.2.1. Stable liquid classes are vendor-specific, for example

pylabrobot.liquid_handling.liquid_classes.hamilton.HamiltonLiquidClass.

• Most frontend methods are async. Backend kwargs and capabilities are

vendor/model specific; a shared frontend does not imply identical behavior.

References

• Liquid handling — operations, tips, tracking,

liquid classes, units, and validation.

• Resources — decks, coordinates, plates, tip racks,

collisions, state, and serialization.

• Hardware backends — verified names,

support levels, capabilities, and live-run gate.

• Analytical equipment — plate readers

and scales.

• Material handling — pumps, heaters,

shakers, temperature control, storage, and centrifuges.

• Visualization — chatterbox, Visualizer,

localhost services, and simulation limits.

Dated upstream sources

Checked 2026-07-23:

• PyPI 0.2.1 — released 2026-03-23;

Python >=3.9; extras and artifacts.

• Stable installation guide

— stable versus source/dev install and optional transport groups.

• Stable API and

supported machines

— 0.2.1 API and model-specific support labels.

• v0.2.1 source tag

and changelog

— tag dated 2026-03-23; Unreleased is development-only.