pudu.assembly

Classes for automated Golden Gate DNA assembly on the Opentrons OT-2.

The module exposes four concrete classes and one factory:

• Domestication — assembles individual parts into a universal acceptor backbone, one part at a time.

• ManualLoopAssembly — combinatorial Loop Assembly from role-based part lists; detects Odd/Even receivers and selects the correct enzyme automatically.

• SBOLLoopAssembly — explicit Loop Assembly from SBOL-format input; each assembly dict specifies parts, backbone, and enzyme directly.

• ManualAssembly — generates a human-readable Markdown bench protocol (no OT-2 commands).

• LoopAssembly — factory that auto-detects input format and returns the appropriate subclass.

All OT-2 classes inherit from BaseAssembly, which implements shared hardware setup, tip management, and liquid transfer.

class pudu.assembly.BaseAssembly(json_params=None, volume_total_reaction=20, volume_part=2, volume_restriction_enzyme=2, volume_t4_dna_ligase=4, volume_t4_dna_ligase_buffer=2, replicates=1, thermocycler_starting_well=0, thermocycler_labware='nest_96_wellplate_100ul_pcr_full_skirt', temperature_module_labware='opentrons_24_aluminumblock_nest_1.5ml_snapcap', temperature_module_position='1', tiprack_labware='opentrons_96_tiprack_20ul', tiprack_positions=None, pipette='p20_single_gen2', pipette_position='left', initial_tip=None, aspiration_rate=0.5, dispense_rate=1, take_picture=False, take_video=False, water_testing=False, output_xlsx=True, protocol_name='')

Bases: ABC

Abstract base class for Loop Assembly protocols. Contains shared hardware setup, liquid handling, and tip management functionality.

Parameters:

• json_params (Dict | None)

• volume_total_reaction (float)

• volume_part (float)

• volume_restriction_enzyme (float)

• volume_t4_dna_ligase (float)

• volume_t4_dna_ligase_buffer (float)

• replicates (int)

• thermocycler_starting_well (int)

• thermocycler_labware (str)

• temperature_module_labware (str)

• temperature_module_position (str)

• tiprack_labware (str)

• tiprack_positions (List[str] | None)

• pipette (str)

• pipette_position (str)

• initial_tip (str | None)

• aspiration_rate (float)

• dispense_rate (float)

• take_picture (bool)

• take_video (bool)

• water_testing (bool)

• output_xlsx (bool)

• protocol_name (str)

__init__(json_params=None, volume_total_reaction=20, volume_part=2, volume_restriction_enzyme=2, volume_t4_dna_ligase=4, volume_t4_dna_ligase_buffer=2, replicates=1, thermocycler_starting_well=0, thermocycler_labware='nest_96_wellplate_100ul_pcr_full_skirt', temperature_module_labware='opentrons_24_aluminumblock_nest_1.5ml_snapcap', temperature_module_position='1', tiprack_labware='opentrons_96_tiprack_20ul', tiprack_positions=None, pipette='p20_single_gen2', pipette_position='left', initial_tip=None, aspiration_rate=0.5, dispense_rate=1, take_picture=False, take_video=False, water_testing=False, output_xlsx=True, protocol_name='')

Initialize shared assembly protocol parameters.

Parameters provided via json_params take precedence over defaults but are overridden by any keyword argument that differs from its default value.

Parameters:

• json_params (Dict | None) – Optional dict of parameter overrides loaded from a JSON config file. Keys must match the parameter names listed below.

• volume_total_reaction (float) – Total volume of each assembly reaction in µL.

• volume_part (float) – Volume of each DNA part (and backbone) added per reaction in µL.

• volume_restriction_enzyme (float) – Volume of restriction enzyme per reaction in µL.

• volume_t4_dna_ligase (float) – Volume of T4 DNA ligase per reaction in µL.

• volume_t4_dna_ligase_buffer (float) – Volume of T4 DNA ligase buffer per reaction in µL.

• replicates (int) – Number of reaction replicates per unique assembly combination.

• thermocycler_starting_well (int) – Zero-based index of the first well to use in the thermocycler plate. Useful when chaining multiple protocols on one plate.

• thermocycler_labware (str) – Opentrons labware definition string for the thermocycler plate.

• temperature_module_labware (str) – Opentrons labware definition string for the aluminum block loaded on the temperature module.

• temperature_module_position (str) – Deck slot number (as a string) for the temperature module.

• tiprack_labware (str) – Opentrons labware definition string for tip racks.

• tiprack_positions (List[str] | None) – List of deck slot strings for tip racks. Defaults to ['2', '3', '4', '5', '6', '9'] when None.

• pipette (str) – Opentrons pipette model string (e.g. 'p20_single_gen2').

• pipette_position (str) – Mount side for the pipette ('left' or 'right').

• initial_tip (str | None) – Well name of the first tip to use on the first rack (e.g. 'B1'). When None, starts from the first available tip ('A1').

• aspiration_rate (float) – Aspiration speed as a fraction of the pipette’s maximum flow rate (1.0 = full speed). Lower values reduce bubble formation.

• dispense_rate (float) – Dispense speed as a fraction of the pipette’s maximum flow rate.

• take_picture (bool) – If True, capture an image at the start and end of the protocol using the OT-2 camera.

• take_video (bool) – If True, record video for the duration of the protocol.

• water_testing (bool) – If True, skip temperature control and thermocycling so the protocol can be simulated with water as a dry run.

• output_xlsx (bool) – If True, write an Excel file summarising the deck layout during simulation.

• protocol_name (str) – Base name used for output files (e.g. the Excel workbook).

abstractmethod process_assemblies()

Process input assemblies - format-specific implementation

setup_tip_management(protocol)

Setup batch tip management for high-throughput applications.

liquid_transfer(protocol, pipette, volume, source, dest, asp_rate=0.5, disp_rate=1.0, blow_out=True, touch_tip=False, mix_before=0.0, mix_after=0.0, mix_reps=3, new_tip=True, drop_tip=True)

Aspirate from source and dispense into dest with optional mixing and tip management.

Automatically triggers a tip-rack batch swap when the current racks are exhausted (see setup_tip_management).

Parameters:

• protocol – Opentrons ProtocolContext used for comments and labware moves.

• pipette – Loaded pipette instrument object.

• volume – Volume to transfer in µL.

• source – Source well or location object.

• dest – Destination well or location object.

• asp_rate (float) – Aspiration speed as a fraction of max flow rate.

• disp_rate (float) – Dispense speed as a fraction of max flow rate.

• blow_out (bool) – If True, blow out after dispensing to clear the tip.

• touch_tip (bool) – If True, touch the tip to the well wall after dispensing to remove hanging droplets.

• mix_before (float) – If > 0, mix this volume at source before aspirating.

• mix_after (float) – If > 0, mix this volume at dest after dispensing.

• mix_reps (int) – Number of mix repetitions when mix_before or mix_after > 0.

• new_tip (bool) – If True, pick up a fresh tip before the transfer.

• drop_tip (bool) – If True, drop the tip after the transfer.

get_xlsx_output(name)

Parameters:

name (str)

run(protocol)

Main protocol execution - uses template method pattern

Parameters:

protocol (ProtocolContext)

class pudu.assembly.Domestication(assembly_data=None, json_params=None, assemblies=None, *args, **kwargs)

Bases: BaseAssembly

Domestication Assembly - inserts individual parts into universal acceptor backbone. Each part is assembled separately with the backbone to create domesticated parts.

Parameters:

• assembly_data (Dict | None)

• json_params (str | None)

• assemblies (List[Dict] | None)

__init__(assembly_data=None, json_params=None, assemblies=None, *args, **kwargs)

Initialize Domestication Assembly protocol.

Parameters:

• assembly_data (Dict | None) – Dict containing ‘assemblies’ key (new standardized approach)

• advanced_params – Optional advanced parameters

• assemblies (List[Dict] | None) – List of assembly dicts (backward compatibility)

• *args – Passed to BaseAssembly

• **kwargs – Passed to BaseAssembly

• json_params (str | None)

process_assemblies()

Process domestication assembly input and validate format

class pudu.assembly.ManualLoopAssembly(assembly_data=None, json_params=None, assemblies=None, *args, **kwargs)

Bases: BaseAssembly

Manual/Combinatorial Loop Assembly - generates combinations from roles. Supports Odd/Even pattern detection for automatic enzyme selection.

Parameters:

• assembly_data (Dict | None)

• json_params (str | None)

• assemblies (List[Dict] | None)

__init__(assembly_data=None, json_params=None, assemblies=None, *args, **kwargs)

Initialize Manual Loop Assembly protocol.

Parameters:

• assembly_data (Dict | None) – Dict containing ‘assemblies’ key (new standardized approach)

• json_params (str | None) – Optional advanced parameters

• assemblies (List[Dict] | None) – List of assembly dicts (backward compatibility)

• *args – Passed to BaseAssembly

• **kwargs – Passed to BaseAssembly

process_assemblies()

Process manual format assemblies and generate combinations

class pudu.assembly.SBOLLoopAssembly(assembly_data=None, json_params=None, assemblies=None, *args, **kwargs)

Bases: BaseAssembly

SBOL Loop Assembly - handles explicit assembly dictionaries from SBOL format. Each assembly dictionary represents one specific construct to build.

Parameters:

• assembly_data (Dict | None)

• json_params (str | None)

• assemblies (List[Dict] | None)

__init__(assembly_data=None, json_params=None, assemblies=None, *args, **kwargs)

Initialize SBOL Loop Assembly protocol.

Parameters:

• assembly_data (Dict | None) – Dict containing ‘assemblies’ key (new standardized approach)

• advanced_params – Optional advanced parameters

• assemblies (List[Dict] | None) – List of assembly dicts (backward compatibility)

• *args – Passed to BaseAssembly

• **kwargs – Passed to BaseAssembly

• json_params (str | None)

process_assemblies()

Process SBOL format assemblies - each is explicit, no combinations needed

class pudu.assembly.ManualAssembly(assembly_data=None, json_params=None, assemblies=None, thermocycling_profile=None, thermocycling_cycles=75, denaturation_profile=None, hold_temperature=4, *args, **kwargs)

Bases: BaseAssembly

Manual Golden Gate assembly protocol generator from SBOL-style JSON input. Produces structured reaction records and renders human-readable Markdown.

Parameters:

• assembly_data (Dict | None)

• json_params (str | None)

• assemblies (List[Dict] | None)

• thermocycling_profile (List[Dict[str, float]] | None)

• thermocycling_cycles (int)

• denaturation_profile (List[Dict[str, float]] | None)

• hold_temperature (float)

__init__(assembly_data=None, json_params=None, assemblies=None, thermocycling_profile=None, thermocycling_cycles=75, denaturation_profile=None, hold_temperature=4, *args, **kwargs)

Initialize shared assembly protocol parameters.

Parameters provided via json_params take precedence over defaults but are overridden by any keyword argument that differs from its default value.

Parameters:

• json_params (str | None) – Optional dict of parameter overrides loaded from a JSON config file. Keys must match the parameter names listed below.

• volume_total_reaction – Total volume of each assembly reaction in µL.

• volume_part – Volume of each DNA part (and backbone) added per reaction in µL.

• volume_restriction_enzyme – Volume of restriction enzyme per reaction in µL.

• volume_t4_dna_ligase – Volume of T4 DNA ligase per reaction in µL.

• volume_t4_dna_ligase_buffer – Volume of T4 DNA ligase buffer per reaction in µL.

• replicates – Number of reaction replicates per unique assembly combination.

• thermocycler_starting_well – Zero-based index of the first well to use in the thermocycler plate. Useful when chaining multiple protocols on one plate.

• thermocycler_labware – Opentrons labware definition string for the thermocycler plate.

• temperature_module_labware – Opentrons labware definition string for the aluminum block loaded on the temperature module.

• temperature_module_position – Deck slot number (as a string) for the temperature module.

• tiprack_labware – Opentrons labware definition string for tip racks.

• tiprack_positions – List of deck slot strings for tip racks. Defaults to ['2', '3', '4', '5', '6', '9'] when None.

• pipette – Opentrons pipette model string (e.g. 'p20_single_gen2').

• pipette_position – Mount side for the pipette ('left' or 'right').

• initial_tip – Well name of the first tip to use on the first rack (e.g. 'B1'). When None, starts from the first available tip ('A1').

• aspiration_rate – Aspiration speed as a fraction of the pipette’s maximum flow rate (1.0 = full speed). Lower values reduce bubble formation.

• dispense_rate – Dispense speed as a fraction of the pipette’s maximum flow rate.

• take_picture – If True, capture an image at the start and end of the protocol using the OT-2 camera.

• take_video – If True, record video for the duration of the protocol.

• water_testing – If True, skip temperature control and thermocycling so the protocol can be simulated with water as a dry run.

• output_xlsx – If True, write an Excel file summarising the deck layout during simulation.

• protocol_name – Base name used for output files (e.g. the Excel workbook).

• assembly_data (Dict | None)

• assemblies (List[Dict] | None)

• thermocycling_profile (List[Dict[str, float]] | None)

• thermocycling_cycles (int)

• denaturation_profile (List[Dict[str, float]] | None)

• hold_temperature (float)

process_assemblies()

Parse and validate input assemblies, then build reaction records.

render_markdown()

Render a complete manual protocol in Markdown format.

Return type:

str

write_markdown(output_path)

Write rendered Markdown protocol to disk.

Parameters:

output_path (str)

class pudu.assembly.LoopAssembly(assemblies, *args, **kwargs)

Bases: object

Factory class that auto-detects input format and returns appropriate subclass. Supports both manual/combinatorial and SBOL format assemblies.

Parameters:

assemblies (List[Dict])

class pudu.assembly.ManualReactionRecord(product_uri, product_name, backbone_uri, backbone_name, part_uris, part_names, restriction_enzyme_uri, restriction_enzyme_name, number_of_dna_components, total_dna_volume, fixed_reagent_volume, water_volume, total_reaction_volume, reagent_additions=<factory>, notes=<factory>)

Bases: object

Structured representation of one Golden Gate manual assembly reaction.

Parameters:

• product_uri (str)

• product_name (str)

• backbone_uri (str)

• backbone_name (str)

• part_uris (List[str])

• part_names (List[str])

• restriction_enzyme_uri (str)

• restriction_enzyme_name (str)

• number_of_dna_components (int)

• total_dna_volume (float)

• fixed_reagent_volume (float)

• water_volume (float)

• total_reaction_volume (float)

• reagent_additions (List[Dict[str, str]])

• notes (List[str])

product_uri: str

product_name: str

backbone_uri: str

backbone_name: str

part_uris: List[str]

part_names: List[str]

restriction_enzyme_uri: str

restriction_enzyme_name: str

number_of_dna_components: int

total_dna_volume: float

fixed_reagent_volume: float

water_volume: float

total_reaction_volume: float

reagent_additions: List[Dict[str, str]]

notes: List[str]