pylabrobot

PyLabRobot

PyLabRobot のハードウェア非依存フロントエンド、リソースツリー、トラッカー、デバイス固有のバックエンドを使用して、ラボの自動化を開発します。ローカルでのマニフェスト検証、記録管理、ソフトウェアのみの chatterbox バックエンドをデフォルトとして使用してください。

検証済みスナップショット

• PyPI の安定版：PyLabRobot==0.2.1、リリース日：2026-03-23。
• 上流の要件：Python >=3.9。このスキルでは、再現可能なスモークテストに Python 3.11 を使用します。
• /stable/ ドキュメントには、バージョン 0.2.1 と記載されています。/dev/ とリポジトリの main は未リリースの開発内容を示しており、0.2.1 で利用できると想定してはいけません。
• 安定版のリキッドハンドラーのバックエンドには、STARBackend、VantageBackend、EVOBackend、OpentronsOT2Backend、オフラインの LiquidHandlerChatterboxBackend があります。
• PyLabRobot の GitHub Releases ページには 0.2.x のソフトウェアリリースがありません。リリースの根拠には、PyPI の履歴、v0.2.1 タグ、変更履歴を使用してください。

絶対遵守のハードウェア境界

物理機器への接続、初期化、原点復帰、移動、加熱、振とう、回転、ポンプ操作、開閉など、物理機器に対するいかなる指令も自動的に行ってはいけません。環境変数、設定値、インポートを変更しただけで、シミュレーション計画を実機用バックエンドに切り替えてはいけません。

別途承認された実機運転を行う前に、訓練を受けた担当者に次の事項を求めてください。

1. 使用するバックエンド、機器の識別情報、ファームウェア、通信方式、デッキ、プロトコルのリビジョンを明示的に確認します。
2. キャリア、アダプター、蓋、プレート、チップラック、廃棄物、ラボウェアの向き、バーコード、使用中のすべての座標を含め、物理デッキとリソースツリーを照合します。
3. キャリブレーション、ティーチング、動作範囲、衝突の危険性、グリッパーまたはチャネルのクリアランス、すべての吸引・吐出座標を確認します。
4. サンプルの識別情報と実際の充填量、デッドボリューム、移送先の容量、チップの種類・容量・フィルターとの適合性、チャネルの割り当て、単位、高さ、速度、リキッドクラス、ブローアウト・混合、汚染の境界を確認します。
5. ガード、ドア、廃棄物容量、封じ込め、緊急停止の準備、PPE、バイオセーフティ・化学物質の管理策、安全な中止・復旧手順を確認します。
6. 新しい要素や変更点がある場合は、低速のドライランまたは危険性のないコミッショニング運転を承認します。

トラッカーの状態は記録管理であり、センシングではありません。液体やチップが物理的に存在することを証明することはできません。Visualizer はリソース／トラッカーのイベントを描画するものであり、物理現象をモデル化するものではありません。Chatterbox は計画された操作を出力するものであり、キャリブレーション、到達可能性、衝突が起きないこと、液体の挙動、機器の状態を証明するものではありません。

必須の事前確認事項

以下の事項を推測してはいけません。

• 正確な機器モデル、搭載オプション、ファームウェア、コンピューター／OS、通信方式。
• PyLabRobot の安定版のバージョンと必要な追加パッケージ。
• デッキ／デッキ原点、キャリア、アダプター、リソース定義、寸法、座標、向き、動作クリアランス。
• プレート／チューブ／リザーバーの容量とデッドボリューム、初期の物理的な液量。
• チップのモデル、フィルター、適合性、容量、ラックの状態、チャネル数、チャネルの割り当て。
• 移送単位（uL、mm、uL/s、s）、高さ、速度、混合、エアギャップ、ブローアウト、液体の特性、検証済みのメーカー指定リキッドクラス。
• 汚染に関するポリシー、コントロール、廃棄物の処理、オペレーターによる介入、受け入れ基準、復旧手順。

情報が不足している場合は、前提条件／阻害要因の一覧を作成し、オフライン用のドラフトのみを作成してください。

再現可能なインストール

オフラインでの API 調査と chatterbox シミュレーションには、次を使用します。

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

Windows では、.venv-pylabrobot\Scripts\python.exe を使用してください。ユーザーが機器を指定し、通信方式の依存関係を明示的に承認するまでは、ハードウェア用の追加パッケージをインストールしてはいけません。その後、該当する安定版のデバイスページを確認してから、"PyLabRobot[serial]==0.2.1" または "PyLabRobot[usb]==0.2.1" のようなバージョンを固定した依存関係を検討してください。

オフライン優先のワークフロー

リポジトリのルートから実行してください。バンドルされている CLI はすべて、厳格な制限付きの UTF-8 JSON/CSV、ローカルの非シンボリックリンクパス、固定の許可リストを使用し、JSON を出力します。ライブバックエンドを選択できるものはありません。

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

ジオメトリチェッカーは、保守的な静的軸平行ボックスを使用します。モーションプランナーではありません。移送プランナーでは、各行に新しいチップが 1 本必要で、ソース／廃液／移送先の容量、チップ容量、ウェル、チャネル、高さ、速度、単位、許可リストを確認します。プロジェクト固有のマニフェストを作成する前に、 assets/protocol-manifest.schema.json と合成フィクスチャを確認してください。

検証済みのソフトウェアのみを使用する例

以下の正確なバックエンドはソフトウェアのみで動作します。ハードウェアバックエンドに置き換えないでください。

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 ルール

• 現在の名前は STARBackend、VantageBackend、EVOBackend、OpentronsOT2Backend です。古い STAR、TecanBackend、OpentronsBackend、ChatterboxBackend のインポートは使用しないでください。
• 汎用のオフライン液体ハンドラーのテストには LiquidHandlerChatterboxBackend を使用してください。ChatterBoxBackend は別の旧名のエクスポートです。両者を混同しないでください。
• Visualizer(resource=...) は有効です。その後、await vis.setup() と await vis.stop() を呼び出します。これは localhost の HTTP/WebSocket サーバーを起動し、ブラウザーを開く場合があります。
• 0.2.1 には、汎用の from pylabrobot.liquid_handling import LiquidClass はありません。安定した液体クラスはベンダー固有です。たとえば pylabrobot.liquid_handling.liquid_classes.hamilton.HamiltonLiquidClass があります。
• フロントエンドメソッドの多くは非同期です。バックエンドのキーワード引数と機能はベンダー／モデル固有です。共通のフロントエンドを使っていても、動作が同一とは限りません。

参考資料

• 液体ハンドリング — 操作、チップ、追跡、液体クラス、単位、検証。
• リソース — デッキ、座標、プレート、チップラック、衝突、状態、シリアライズ。
• ハードウェアバックエンド — 検証済みの名前、サポートレベル、機能、ライブ実行のゲート。
• 分析機器 — プレートリーダーと秤。
• マテリアルハンドリング — ポンプ、ヒーター、シェーカー、温度制御、保管、遠心機。
• 可視化 — chatterbox、Visualizer、localhost サービス、シミュレーションの制限。

日付付きの上流ソース

2026-07-23 に確認：

• PyPI 0.2.1 — 2026-03-23 リリース、Python >=3.9、追加機能と成果物。
• 安定版インストールガイド — 安定版インストールとソース／開発版インストールの違い、およびオプションのトランスポートグループ。
• 安定版 API と 対応機器 — 0.2.1 の API と、モデル固有のサポートラベル。
• v0.2.1 ソースタグ と変更履歴 — タグの日付は 2026-03-23、Unreleased は開発版のみです。

エージェントの運用手順

1. 環境を確認します。 装置またはプラットフォームのモデル、API バージョン、認証情報、シミュレーターが利用可能かどうかを確認します。
2. 入力を明確にします。 データまたはユーザーから形式、識別子、パラメーターを確認します。結果に影響する値は推測せず、質問してください。
3. まず小規模なバージョンを実行します。 実サンプルを使用する前に、プロトコルをシミュレーションするか、水またはダミーのラボウェアを使って実行します。
4. 上記の手順と参考情報を使って、タスク全体を実行します。
5. 結果を検証します。 容量、デッキレイアウト、ラボウェアの定義を確認し、実行前に人間の承認を得てください。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未確認の事項を伝えます。

次のことが起きた場合	対応方法
シミュレーションでプロトコルが失敗する	シミュレーションで修正してください。検証していないプロトコルをハードウェアで実行してはいけません。
これらの手順に記載された関数、フラグ、エンドポイントがインストール済みバージョンに存在しない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して調整し、ユーザーに伝えてください。API を捏造してはいけません。
必須の入力、識別子、パラメーターが曖昧である	ユーザーに質問するか、実行前に仮定を明示してください。

誠実性に関するルール

• 結果、パラメーター、識別子、引用、統計を捏造してはいけません。実行または検証できない場合は、その旨を明確に伝えてください。
• ユーザーから明示的な確認を得ずに、物理的な操作、注文、課金を発生させてはいけません。
• ここに記載されたバージョン固有の詳細は古くなっている可能性があるため、インストール済みバージョンの公式ドキュメントで確認してください。
• 費用がかかる操作、共有 GPU やクラウドクォータを消費する操作、個人データや患者データを扱う操作、取り消せない操作の前には確認してください。

関連スキル

• opentrons-integration：Flex および OT-2 ロボット向けの公式 Opentrons Python Protocol API v2 プロトコルの作成、レビュー、移行、シミュレーション、トラブルシューティングを行います。
• fluidsim：数値的妥当性が明確な、範囲を限定した FluidSim の計算流体力学シミュレーションを計画、設定、検査、再開、分析します。…