pylabrobot · diff
git:20260611.1b8fae3 to v1.1
175 added, 137 removed. Audit A to A.
---
name: pylabrobot
- description: Vendor-agnostic lab automation framework. Use when controlling multiple equipment types (Hamilton, Tecan, Opentrons, plate readers, pumps) or needing unified programming across different vendors. Best for complex workflows, multi-vendor setups, simulation. For Opentrons-only protocols with official API, opentrons-integration may be simpler.
- license: MIT license
- metadata: {"version": "1.0", "skill-author": "K-Dense Inc."}
+ description: Develop and review PyLabRobot lab-automation resources, liquid-handling plans, offline simulations, and supported-device integrations. Use for PyLabRobot protocols or API questions; keep physical execution behind an explicit operator safety gate.
+ license: MIT
+ compatibility: Verified against PyLabRobot 0.2.1 on Python 3.9+. Bundled planning CLIs require only Python 3.11+ and make no serial, USB, or network connections. Physical devices need model-specific extras, configuration, calibration, and trained operator approval.
+ allowed-tools:
+ - Read
+ - Write
+ - Edit
+ - Bash
+ metadata:
+ version: "1.1"
+ skill-author: "K-Dense Inc."
+ pylabrobot-version: "0.2.1"
+ researched: "2026-07-23"
---
# PyLabRobot
- ## Overview
-
- PyLabRobot is a hardware-agnostic, pure Python Software Development Kit for automated and autonomous laboratories. Use this skill to control liquid handling robots, plate readers, pumps, heater shakers, incubators, centrifuges, and other laboratory automation equipment through a unified Python interface that works across platforms (Windows, macOS, Linux).
+ 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.
- ## When to Use This Skill
+ ## Verified snapshot
- Use this skill when:
- - Programming liquid handling robots (Hamilton STAR/STARlet, Opentrons OT-2, Tecan EVO)
- - Automating laboratory workflows involving pipetting, sample preparation, or analytical measurements
- - Managing deck layouts and laboratory resources (plates, tips, containers, troughs)
- - Integrating multiple lab devices (liquid handlers, plate readers, heater shakers, pumps)
- - Creating reproducible laboratory protocols with state management
- - Simulating protocols before running on physical hardware
- - Reading plates using BMG CLARIOstar or other supported plate readers
- - Controlling temperature, shaking, centrifugation, or other material handling operations
- - Working with laboratory automation in Python
+ - 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.
- ## Core Capabilities
+ ## Non-negotiable hardware boundary
- PyLabRobot provides comprehensive laboratory automation through six main capability areas, each detailed in the references/ directory:
+ 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.
- ### 1. Liquid Handling (`references/liquid-handling.md`)
+ Before any separately authorized live run, require a trained human to:
- Control liquid handling robots for aspirating, dispensing, and transferring liquids. Key operations include:
- - **Basic Operations**: Aspirate, dispense, transfer liquids between wells
- - **Tip Management**: Pick up, drop, and track pipette tips automatically
- - **Advanced Techniques**: Multi-channel pipetting, serial dilutions, plate replication
- - **Volume Tracking**: Automatic tracking of liquid volumes in wells
- - **Hardware Support**: Hamilton STAR/STARlet, Opentrons OT-2, Tecan EVO, and others
+ 1. Explicitly confirm the exact backend, device identity, firmware, transport,
+ deck, and protocol revision.
+ 2. Reconcile the physical deck against the resource tree, including carriers,
+ adapters, lids, plates, tip racks, waste, labware orientation, barcodes, and
+ every occupied coordinate.
+ 3. Verify calibration, teaching, motion envelopes, collision risks, gripper or
+ channel clearances, and all aspiration/dispense coordinates.
+ 4. 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.
+ 5. Confirm guards, doors, waste capacity, containment, emergency stop readiness,
+ PPE, biosafety/chemical controls, and a safe abort/recovery procedure.
+ 6. Approve a slow dry run or nonhazardous commissioning run when anything is
+ new or changed.
- ### 2. Resource Management (`references/resources.md`)
+ 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.
- Manage laboratory resources in a hierarchical system:
- - **Resource Types**: Plates, tip racks, troughs, tubes, carriers, and custom labware
- - **Deck Layout**: Assign resources to deck positions with coordinate systems
- - **State Management**: Track tip presence, liquid volumes, and resource states
- - **Serialization**: Save and load deck layouts and states from JSON files
- - **Resource Discovery**: Access wells, tips, and containers through intuitive APIs
+ ## Required intake
- ### 3. Hardware Backends (`references/hardware-backends.md`)
+ Do not guess any of these:
- Connect to diverse laboratory equipment through backend abstraction:
- - **Liquid Handlers**: Hamilton STAR (full support), Opentrons OT-2, Tecan EVO
- - **Simulation**: ChatterboxBackend for protocol testing without hardware
- - **Platform Support**: Works on Windows, macOS, Linux, and Raspberry Pi
- - **Backend Switching**: Change robots by swapping backend without rewriting protocols
+ - 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.
- ### 4. Analytical Equipment (`references/analytical-equipment.md`)
+ If information is missing, produce an assumptions/blockers list and an offline
+ draft only.
- Integrate plate readers and analytical instruments:
- - **Plate Readers**: BMG CLARIOstar for absorbance, luminescence, fluorescence
- - **Scales**: Mettler Toledo integration for mass measurements
- - **Integration Patterns**: Combine liquid handlers with analytical equipment
- - **Automated Workflows**: Move plates between devices automatically
+ ## Reproducible install
- ### 5. Material Handling (`references/material-handling.md`)
+ For offline API inspection and chatterbox simulation:
- Control environmental and material handling equipment:
- - **Heater Shakers**: Hamilton HeaterShaker, Inheco ThermoShake
- - **Incubators**: Inheco and Thermo Fisher incubators with temperature control
- - **Centrifuges**: Agilent VSpin with bucket positioning and spin control
- - **Pumps**: Cole Parmer Masterflex for fluid pumping operations
- - **Temperature Control**: Set and monitor temperatures during protocols
+ ```bash
+ uv venv --python 3.11 .venv-pylabrobot
+ uv pip install --python .venv-pylabrobot/bin/python "PyLabRobot==0.2.1"
+ ```
- ### 6. Visualization & Simulation (`references/visualization.md`)
+ 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"`.
- Visualize and simulate laboratory protocols:
- - **Browser Visualizer**: Real-time 3D visualization of deck state
- - **Simulation Mode**: Test protocols without physical hardware
- - **State Tracking**: Monitor tip presence and liquid volumes visually
- - **Deck Editor**: Graphical tool for designing deck layouts
- - **Protocol Validation**: Verify protocols before running on hardware
+ ## Offline-first workflow
- ## Quick Start
+ 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.
- To get started with PyLabRobot, install the package and initialize a liquid handler:
+ ```bash
+ python3 skills/pylabrobot/scripts/validate_manifest.py \
+ --input skills/pylabrobot/tests/fixtures/protocol_manifest.json
- ```python
- # Install PyLabRobot
- # uv pip install pylabrobot
+ python3 skills/pylabrobot/scripts/check_deck_geometry.py \
+ --input skills/pylabrobot/tests/fixtures/protocol_manifest.json
- # Basic liquid handling setup
- from pylabrobot.liquid_handling import LiquidHandler
- from pylabrobot.liquid_handling.backends import STAR
- from pylabrobot.resources import STARLetDeck
+ python3 skills/pylabrobot/scripts/plan_transfers.py \
+ --manifest skills/pylabrobot/tests/fixtures/protocol_manifest.json \
+ --transfers skills/pylabrobot/tests/fixtures/transfers.csv
- # Initialize liquid handler
- lh = LiquidHandler(backend=STAR(), deck=STARLetDeck())
- await lh.setup()
+ python3 skills/pylabrobot/scripts/generate_simulation_plan.py \
+ --manifest skills/pylabrobot/tests/fixtures/protocol_manifest.json \
+ --transfers skills/pylabrobot/tests/fixtures/transfers.csv
- # Basic operations
- await lh.pick_up_tips(tip_rack["A1:H1"])
- await lh.aspirate(plate["A1"], vols=100)
- await lh.dispense(plate["A2"], vols=100)
- await lh.drop_tips()
+ python3 skills/pylabrobot/scripts/inspect_backends.py \
+ --expected-version 0.2.1 --strict
```
- ## Working with References
-
- This skill organizes detailed information across multiple reference files. Load the relevant reference when:
- - **Liquid Handling**: Writing pipetting protocols, tip management, transfers
- - **Resources**: Defining deck layouts, managing plates/tips, custom labware
- - **Hardware Backends**: Connecting to specific robots, switching platforms
- - **Analytical Equipment**: Integrating plate readers, scales, or analytical devices
- - **Material Handling**: Using heater shakers, incubators, centrifuges, pumps
- - **Visualization**: Simulating protocols, visualizing deck states
-
- All reference files can be found in the `references/` directory and contain comprehensive examples, API usage patterns, and best practices.
-
- ## Best Practices
-
- When creating laboratory automation protocols with PyLabRobot:
-
- 1. **Start with Simulation**: Use ChatterboxBackend and the visualizer to test protocols before running on hardware
- 2. **Enable Tracking**: Turn on tip tracking and volume tracking for accurate state management
- 3. **Resource Naming**: Use clear, descriptive names for all resources (plates, tip racks, containers)
- 4. **State Serialization**: Save deck layouts and states to JSON for reproducibility
- 5. **Error Handling**: Implement proper async error handling for hardware operations
- 6. **Temperature Control**: Set temperatures early as heating/cooling takes time
- 7. **Modular Protocols**: Break complex workflows into reusable functions
- 8. **Documentation**: Reference official docs at https://docs.pylabrobot.org for latest features
+ 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.
- ## Common Workflows
+ ## Verified software-only example
- ### Liquid Transfer Protocol
+ The exact backend below is software-only. Do not substitute a hardware backend.
```python
- # Setup
- lh = LiquidHandler(backend=STAR(), deck=STARLetDeck())
- await lh.setup()
+ 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
- # Define resources
- tip_rack = TIP_CAR_480_A00(name="tip_rack")
- source_plate = Cos_96_DW_1mL(name="source")
- dest_plate = Cos_96_DW_1mL(name="dest")
+ set_tip_tracking(True)
+ set_volume_tracking(True)
- lh.deck.assign_child_resource(tip_rack, rails=1)
- lh.deck.assign_child_resource(source_plate, rails=10)
- lh.deck.assign_child_resource(dest_plate, rails=15)
+ 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
- # Transfer protocol
- await lh.pick_up_tips(tip_rack["A1:H1"])
- await lh.transfer(source_plate["A1:H12"], dest_plate["A1:H12"], vols=100)
- await lh.drop_tips()
+ 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()
```
- ### Plate Reading Workflow
-
- ```python
- # Setup plate reader
- from pylabrobot.plate_reading import PlateReader
- from pylabrobot.plate_reading.clario_star_backend import CLARIOstarBackend
+ ## API rules that prevent stale code
- pr = PlateReader(name="CLARIOstar", backend=CLARIOstarBackend())
- await pr.setup()
+ - 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.
- # Set temperature and read
- await pr.set_temperature(37)
- await pr.open()
- # (manually or robotically load plate)
- await pr.close()
- data = await pr.read_absorbance(wavelength=450)
- ```
+ ## References
- ## Additional Resources
+ - [Liquid handling](references/liquid-handling.md) — operations, tips, tracking,
+ liquid classes, units, and validation.
+ - [Resources](references/resources.md) — decks, coordinates, plates, tip racks,
+ collisions, state, and serialization.
+ - [Hardware backends](references/hardware-backends.md) — verified names,
+ support levels, capabilities, and live-run gate.
+ - [Analytical equipment](references/analytical-equipment.md) — plate readers
+ and scales.
+ - [Material handling](references/material-handling.md) — pumps, heaters,
+ shakers, temperature control, storage, and centrifuges.
+ - [Visualization](references/visualization.md) — chatterbox, Visualizer,
+ localhost services, and simulation limits.
- - **Official Documentation**: https://docs.pylabrobot.org
- - **GitHub Repository**: https://github.com/PyLabRobot/pylabrobot
- - **Community Forum**: https://discuss.pylabrobot.org
- - **PyPI Package**: https://pypi.org/project/PyLabRobot/
+ ## Dated upstream sources
- For detailed usage of specific capabilities, refer to the corresponding reference file in the `references/` directory.
+ Checked **2026-07-23**:
+ - [PyPI 0.2.1](https://pypi.org/project/PyLabRobot/) — released 2026-03-23;
+ Python >=3.9; extras and artifacts.
+ - [Stable installation guide](https://docs.pylabrobot.org/stable/user_guide/_getting-started/installation.html)
+ — stable versus source/dev install and optional transport groups.
+ - [Stable API](https://docs.pylabrobot.org/stable/api/pylabrobot.html) and
+ [supported machines](https://docs.pylabrobot.org/stable/user_guide/machines.html)
+ — 0.2.1 API and model-specific support labels.
+ - [`v0.2.1` source tag](https://github.com/PyLabRobot/pylabrobot/tree/v0.2.1)
+ and [changelog](https://github.com/PyLabRobot/pylabrobot/blob/main/CHANGELOG.md)
+ — tag dated 2026-03-23; `Unreleased` is development-only.