RudgeLab · Gonza10V · Jun 22, 2026 · Apr 25, 2024 · Jan 7, 2025 · Jan 7, 2025
diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-package.yml
@@ -0,0 +1,37 @@
+name: Python package
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 0 * * *'
+
+jobs:
+  build:
+
+    runs-on: [ubuntu-latest]
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v3
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+
+    - name: Install pudu package in development mode with test dependencies
+      run: |
+        pip install -e .[test]
+
+    - name: Test scripts with opentrons_simulate
+      run: |
+        pytest -s -v
diff --git a/.gitignore b/.gitignore
@@ -1 +1,12 @@
-venv
+venv
+
+# Generated protocol output files produced by scripts/manual/ generators
+scripts/manual/*.md
+
+# Sphinx build output
+docs/_build/
+
+# Python cache
+__pycache__/
+*.pyc
+*.egg-info/
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .
+      extra_requirements:
+        - test
diff --git a/README.md b/README.md
@@ -2,8 +2,8 @@
 Welcome to the PUDU (Protocol Unified Design Unit) repository, our Python package for liquid handling robot control on Synthetic Biology workflows.
 
 
-<img src="https://github.com/RudgeLab/PUDU/blob/main/images/PUDU_Logo.png#gh-light-mode-only" alt="PUDU logo" width="250"/>
-<img src="https://github.com/RudgeLab/PUDU/blob/main/images/PUDU_Logo.png#gh-dark-mode-only" alt="PUDU night logo" width="250"/>
+<img src="https://github.com/MyersResearchGroup/PUDU/blob/main/images/PUDU_Logo.png#gh-light-mode-only" alt="PUDU logo" width="250"/>
+<img src="https://github.com/MyersResearchGroup/PUDU/blob/main/images/PUDU_Logo_dark.png#gh-dark-mode-only" alt="PUDU night logo" width="250"/>
 
 ## *The art of automated liquid handling*
 
@@ -46,7 +46,7 @@ Run:
 
 This code can be executed in the terminal and in jupyter notebooks.
 
-For more details please refer to our Wiki (TODO) for installation instructions and developer guides.
+For more details please refer to our [documentation](https://pudu.readthedocs.io/en/latest/) for installation instructions and developer guides.
 
 ### OT-2 installation
 
@@ -62,8 +62,24 @@ then in the OT-2 terminal run:
 
 ## Documentation
 
- Please visit our documentation with API reference at Read the Docs (TODO)
+ Please visit our documentation with full API reference at [pudu.readthedocs.io](https://pudu.readthedocs.io/en/latest/)
 
 ## Tutorials
 
 TODO
+
+## Manual Golden Gate protocol generation
+
+PUDU now supports generating a **human-readable manual Golden Gate protocol** from SBOL-style JSON input using `ManualAssembly`.
+
+- The class builds structured per-reaction records (product, backbone, ordered parts, enzyme, and calculated reagent volumes).
+- It renders a Markdown protocol suitable for lab use and future PDF conversion.
+- It does **not** generate OT-2 commands.
+
+Example script:
+
+```bash
+PYTHONPATH=src python scripts/generate_manual_assembly_protocol.py
+```
+
+This writes a protocol document to `scripts/manual_assembly_protocol.md`.
diff --git a/docs/api/assembly.rst b/docs/api/assembly.rst
@@ -0,0 +1,46 @@
+pudu.assembly
+=============
+
+Classes for automated Golden Gate DNA assembly on the Opentrons OT-2.
+
+The module exposes four concrete classes and one factory:
+
+* :class:`~pudu.assembly.Domestication` — assembles individual parts into a universal acceptor backbone, one part at a time.
+* :class:`~pudu.assembly.ManualLoopAssembly` — combinatorial Loop Assembly from role-based part lists; detects Odd/Even receivers and selects the correct enzyme automatically.
+* :class:`~pudu.assembly.SBOLLoopAssembly` — explicit Loop Assembly from SBOL-format input; each assembly dict specifies parts, backbone, and enzyme directly.
+* :class:`~pudu.assembly.ManualAssembly` — generates a human-readable Markdown bench protocol (no OT-2 commands).
+* :class:`~pudu.assembly.LoopAssembly` — factory that auto-detects input format and returns the appropriate subclass.
+
+All OT-2 classes inherit from :class:`~pudu.assembly.BaseAssembly`, which
+implements shared hardware setup, tip management, and liquid transfer.
+
+.. autoclass:: pudu.assembly.BaseAssembly
+   :members:
+   :special-members: __init__
+
+.. autoclass:: pudu.assembly.Domestication
+   :members:
+   :special-members: __init__
+   :show-inheritance:
+
+.. autoclass:: pudu.assembly.ManualLoopAssembly
+   :members:
+   :special-members: __init__
+   :show-inheritance:
+
+.. autoclass:: pudu.assembly.SBOLLoopAssembly
+   :members:
+   :special-members: __init__
+   :show-inheritance:
+
+.. autoclass:: pudu.assembly.ManualAssembly
+   :members:
+   :special-members: __init__
+   :show-inheritance:
+
+.. autoclass:: pudu.assembly.LoopAssembly
+   :members:
+   :show-inheritance:
+
+.. autoclass:: pudu.assembly.ManualReactionRecord
+   :members:
diff --git a/docs/api/calibration.rst b/docs/api/calibration.rst
@@ -0,0 +1,33 @@
+pudu.calibration
+================
+
+Classes for automated plate-reader calibration following the iGEM 2022
+InterLab calibration protocol.
+
+Two protocols are provided:
+
+* :class:`~pudu.calibration.GFPODCalibration` — two calibrants (fluorescein
+  and silica microspheres), two replicates each; for GFP fluorescence and
+  OD600 calibration.
+* :class:`~pudu.calibration.RGBODCalibration` — four calibrants (fluorescein,
+  sulforhodamine 101, cascade blue, microspheres), two replicates each; for
+  RGB fluorescence and OD600 calibration.
+
+Both subclass :class:`~pudu.calibration.BaseCalibration` and use the
+template-method pattern: ``run()`` is implemented in the base class and calls
+abstract methods for the calibrant-specific steps.
+
+Reference protocol:
+`iGEM 2022 InterLab Calibration Protocol <https://old.igem.org/wiki/images/a/a4/InterLab_2022_-_Calibration_Protocol_v2.pdf>`_
+
+.. autoclass:: pudu.calibration.BaseCalibration
+   :members:
+   :special-members: __init__
+
+.. autoclass:: pudu.calibration.GFPODCalibration
+   :members:
+   :show-inheritance:
+
+.. autoclass:: pudu.calibration.RGBODCalibration
+   :members:
+   :show-inheritance:
diff --git a/docs/api/generate_protocol.rst b/docs/api/generate_protocol.rst
@@ -0,0 +1,12 @@
+pudu.generate_protocol
+======================
+
+Command-line tool and Python API for generating standalone Opentrons ``.py``
+protocol files from JSON inputs.
+
+See the module docstring below for the full CLI flag reference, JSON input
+formats, copy-paste terminal workflow, and Python API usage examples.
+
+.. automodule:: pudu.generate_protocol
+   :members:
+   :undoc-members: False
diff --git a/docs/api/index.rst b/docs/api/index.rst
@@ -0,0 +1,13 @@
+API Reference
+=============
+
+.. toctree::
+   :maxdepth: 1
+
+   assembly
+   transformation
+   plating
+   calibration
+   sample_preparation
+   utils
+   generate_protocol
diff --git a/docs/api/plating.rst b/docs/api/plating.rst
@@ -0,0 +1,27 @@
+pudu.plating
+============
+
+Classes for automated and manual serial-dilution spot plating.
+
+* :class:`~pudu.plating.Plating` — OT-2 protocol that takes transformed
+  bacteria from a thermocycler plate, performs up to two serial dilutions,
+  and spots each dilution onto agar plates with replicates.
+* :class:`~pudu.plating.ManualPlating` — generates a human-readable Markdown
+  bench protocol.
+
+On simulation, :class:`~pudu.plating.Plating` writes:
+
+* ``{protocol_name}.json`` — machine-readable agar plate map
+* ``{protocol_name}.xlsx`` — colour-coded Excel grid (blue = dilution 1, orange = dilution 2)
+
+.. autoclass:: pudu.plating.Plating
+   :members:
+   :special-members: __init__
+
+.. autoclass:: pudu.plating.ManualPlating
+   :members:
+   :special-members: __init__
+   :show-inheritance:
+
+.. autoclass:: pudu.plating.ManualPlatingRecord
+   :members:
diff --git a/docs/api/sample_preparation.rst b/docs/api/sample_preparation.rst
@@ -0,0 +1,28 @@
+pudu.sample_preparation
+========================
+
+Classes for distributing samples and creating inducer gradients on 96-well
+plates for characterisation experiments.
+
+* :class:`~pudu.sample_preparation.PlateSamples` — distributes a list of
+  samples into replicate wells across a plate.
+* :class:`~pudu.sample_preparation.PlateWithGradient` — creates a serial
+  inducer-concentration gradient (e.g. IPTG dose-response) across replicate
+  rows on a 96-well plate.
+
+Both subclass :class:`~pudu.sample_preparation.SamplePreparation`, which
+provides shared labware loading and well-slot management.
+
+.. autoclass:: pudu.sample_preparation.SamplePreparation
+   :members:
+   :special-members: __init__
+
+.. autoclass:: pudu.sample_preparation.PlateSamples
+   :members:
+   :special-members: __init__
+   :show-inheritance:
+
+.. autoclass:: pudu.sample_preparation.PlateWithGradient
+   :members:
+   :special-members: __init__
+   :show-inheritance:
diff --git a/docs/api/transformation.rst b/docs/api/transformation.rst
@@ -0,0 +1,37 @@
+pudu.transformation
+===================
+
+Classes for automated and manual bacterial heat-shock transformation.
+
+* :class:`~pudu.transformation.HeatShockTransformation` — OT-2 protocol that
+  loads DNA and competent cells into a thermocycler plate, runs the heat-shock
+  cycle, adds recovery media, and exports a plating map.
+* :class:`~pudu.transformation.ManualTransformation` — generates a
+  human-readable Markdown bench protocol.
+
+Both classes accept SBOL-style transformation data of the form::
+
+    [
+        {
+            "Strain":   "https://SBOL2Build.org/strain_GFP/1",
+            "Chassis":  "https://sbolcanvas.org/DH5alpha/1",
+            "Plasmids": ["https://SBOL2Build.org/composite_1/1"]
+        }
+    ]
+
+.. autoclass:: pudu.transformation.Transformation
+   :members:
+   :special-members: __init__
+
+.. autoclass:: pudu.transformation.HeatShockTransformation
+   :members:
+   :special-members: __init__
+   :show-inheritance:
+
+.. autoclass:: pudu.transformation.ManualTransformation
+   :members:
+   :special-members: __init__
+   :show-inheritance:
+
+.. autoclass:: pudu.transformation.ManualTransformationRecord
+   :members:
diff --git a/docs/api/utils.rst b/docs/api/utils.rst
@@ -0,0 +1,22 @@
+pudu.utils
+==========
+
+Shared utilities used across PUDU protocols.
+
+* :class:`~pudu.utils.Camera` — captures images and records video via ffmpeg
+  during OT-2 protocol runs.
+* :class:`~pudu.utils.SmartPipette` — pipette wrapper that uses the
+  Opentrons liquid-tracking API to compute safe aspiration heights for
+  conical tubes, preventing tip plunging as tubes empty.
+* ``colors`` — list of 24 hex colour strings used to colour-code liquids in
+  the Opentrons deck visualiser.
+
+.. autodata:: pudu.utils.colors
+
+.. autoclass:: pudu.utils.Camera
+   :members:
+   :special-members: __init__
+
+.. autoclass:: pudu.utils.SmartPipette
+   :members:
+   :special-members: __init__