Introduce buildcompiler.protocols subpackage with native OT-2 Python and JSON implementations of assembly, transformation, and plating

.github/workflows/ci.yml

@@ -11,6 +11,7 @@ jobs:
   core:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
         python-version: ["3.10", "3.11"]
     steps:
@@ -21,8 +22,7 @@ jobs:
       - name: Install package
         run: |
           python -m pip install -U pip
-          python -m pip install -e ".[test]"
-          python -m pip install ruff
+          python -m pip install -e ".[dev,automation]"
       - name: Ruff check
         run: >-
           ruff check
@@ -35,10 +35,12 @@ jobs:
           src/buildcompiler/adapters
           src/buildcompiler/reporting
           src/buildcompiler/domain
+          src/buildcompiler/protocols
           tests/conftest.py
           tests/unit
           tests/stages
           tests/integration
+          tests/automation
       - name: Ruff format check
         run: >-
           ruff format --check
@@ -51,9 +53,36 @@ jobs:
           src/buildcompiler/adapters
           src/buildcompiler/reporting
           src/buildcompiler/domain
+          src/buildcompiler/protocols
           tests/conftest.py
           tests/unit
           tests/stages
           tests/integration
+          tests/automation
       - name: Core tests
         run: pytest tests/unit tests/stages tests/integration -q
+
+  protocol-equivalence:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
+        with:
+          repository: MyersResearchGroup/PUDU
+          ref: cdf7bde2128871c889fb25a4a0c168d5d8f0c1d3
+          path: .reference/PUDU
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - name: Install simulator and test dependencies
+        run: python -m pip install -e '.[test,automation]'
+      - name: Compare against pinned PUDU in the Opentrons simulator
+        env:
+          PUDU_REPOSITORY: ${{ github.workspace }}/.reference/PUDU
+          BUILDCOMPILER_REQUIRE_EQUIVALENCE: "1"
+        run: pytest tests/automation -q --basetemp=.equivalence-traces
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: protocol-equivalence-traces
+          path: .equivalence-traces

LICENSE

@@ -1,6 +1,7 @@
 MIT License
 
 Copyright (c) 2025 Genetic Logic Lab
+Portions copyright (c) 2022 Rudge Lab
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -37,7 +37,7 @@ The compiler should answer:
 - Produce in-memory PUDU-compatible JSON intermediates in compiler-only mode.
 - Chain successful assembly/domestication products to transformation and plating, deduplicated by product identity.
 - Return structured statuses, missing inputs, required approvals, warnings, summaries, and optional detailed reports.
-- Keep PUDU protocol generation and Opentrons simulation optional.
+- Compile assembly, transformation and plating protocols natively; keep Opentrons simulation optional. See the [protocol compiler guide](docs/protocols.rst).
 
 ## Non-goals for v1
 
@@ -183,7 +183,7 @@ print(result.artifact_bundle.manifest)
 ```
 
 `MANUAL` writes canonical JSON, a human-readable procedure, and a hash manifest.
-`AUTOMATED` additionally generates PUDU Python protocols; setting
+`AUTOMATED` additionally generates standalone OT-2 Python protocols and their handoff artifacts; setting
 `options.protocol.simulate = True` runs `opentrons_simulate` and treats a nonzero
 exit code as a protocol-stage failure. File-producing modes require an explicit
 `results_dir` and reject a nonempty directory unless `overwrite=True`.
@@ -255,7 +255,7 @@ docker compose run --rm app ruff format --check .
 docker compose run --rm app pytest
 ```
 
-Core CI should not require PUDU or Opentrons. Those dependencies are optional and should live behind optional test jobs or manual workflows.
+Core CI does not require PUDU or Opentrons. A separate acceptance job compares native protocols against a pinned PUDU checkout using Opentrons 8.8.2.
 
 ## Testing and quality checks
 
@@ -278,7 +278,7 @@ Testing priorities:
 7. SBOL assembly service port using existing fixtures.
 8. Transformation and plating deduplication.
 9. Summary/report/graph generation.
-10. Optional PUDU/Opentrons adapter smoke tests.
+10. PUDU equivalence in the real Opentrons simulator, including the connected assembly/transformation/plating workflow.
 
 ## How ChatGPT and Codex should use these docs
 

docs/API_Reference.rst

@@ -23,6 +23,14 @@ buildcompiler.api.options
    :undoc-members:
    :show-inheritance:
 
+buildcompiler.api.protocols
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: buildcompiler.api.protocols
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 buildcompiler.api.serialization
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -31,6 +39,81 @@ buildcompiler.api.serialization
    :undoc-members:
    :show-inheritance:
 
+Protocols
+---------
+
+buildcompiler.protocols.backends.markdown
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: buildcompiler.protocols.backends.markdown
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+buildcompiler.protocols.backends.opentrons_ot2_json
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: buildcompiler.protocols.backends.opentrons_ot2_json
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+buildcompiler.protocols.backends.opentrons_ot2_python
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: buildcompiler.protocols.backends.opentrons_ot2_python
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+buildcompiler.protocols.backends.simulation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: buildcompiler.protocols.backends.simulation
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+buildcompiler.protocols.compiler
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: buildcompiler.protocols.compiler
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+buildcompiler.protocols.methods.assembly
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: buildcompiler.protocols.methods.assembly
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+buildcompiler.protocols.methods.plating
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: buildcompiler.protocols.methods.plating
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+buildcompiler.protocols.methods.transformation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: buildcompiler.protocols.methods.transformation
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+buildcompiler.protocols.models
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: buildcompiler.protocols.models
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Stages
 ------
 
@@ -262,6 +345,22 @@ buildcompiler.domain.plasmid
    :undoc-members:
    :show-inheritance:
 
+buildcompiler.domain.protocol
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: buildcompiler.domain.protocol
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+buildcompiler.domain.protocol_requests
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: buildcompiler.domain.protocol_requests
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 buildcompiler.domain.reagent
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/development.rst

@@ -8,7 +8,9 @@ Install the package and test dependencies:
 
 .. code-block:: bash
 
-   python -m pip install -e ".[test]"
+   python -m pip install -e ".[dev]"
+
+The ``dev`` extra pins the same Ruff version used by CI.
 
 Run the focused tests for the documented PUDU path:
 
@@ -19,12 +21,21 @@ Run the focused tests for the documented PUDU path:
        tests/unit/adapters/pudu/test_plating_json.py \
        tests/test_buildcompiler_transformation.py
 
+Run native protocol acceptance separately in the Python 3.10 simulation
+environment described in ``tests/automation/README.md``:
+
+.. code-block:: bash
+
+   PUDU_REPOSITORY=../PUDU BUILDCOMPILER_REQUIRE_EQUIVALENCE=1 \
+       python -m pytest tests/automation -q
+
 Build docs locally:
 
 .. code-block:: bash
 
    python -m pip install -r docs/requirements.txt
-   sphinx-build -b html docs docs/_build/html
+   python tools/update_api_reference.py
+   sphinx-build -b html -W --keep-going docs docs/_build/html
 
 Agent handoff
 -------------

docs/index.rst

@@ -43,6 +43,7 @@ Representative use cases
 
    installation
    quickstart
+   protocols
    examples/offline_lvl1
    examples/transformation_pudu
    examples/full_build

docs/installation.rst

@@ -24,20 +24,24 @@ Install test dependencies:
 Optional automation dependencies
 --------------------------------
 
-PUDU and Opentrons support are optional. BuildCompiler can emit PUDU-compatible
-JSON without importing PUDU. To generate or simulate OT-2 protocols, install the
-automation dependencies or use a local PUDU checkout:
+Python protocol compilation and structured handoffs are included in the core
+package. The ``automation`` extra includes JSON protocol compilation, the
+Opentrons simulator and inventory integration:
 
 .. code-block:: bash
 
-   python -m pip install -e ".[automation,test]"
+   python -m pip install -e ".[automation]"
 
-In the development environment used for the repository examples, PUDU was
-available as a sibling checkout:
+To run the pinned simulator and equivalence tests, use Python 3.10 and add the
+test dependencies:
 
-.. code-block:: text
+.. code-block:: bash
+
+   python -m pip install -e ".[test,automation]"
 
-   /Users/gonzalovidal/Documents/GitHub/PUDU
+The equivalence suite additionally needs a PUDU reference checkout, as described
+in ``tests/automation/README.md``. Generated native scripts do not need PUDU.
+See :doc:`protocols` for compilation, artifact writing and handoffs.
 
 Read the Docs
 -------------