Metadata-Version: 2.4
Name: synbio-buildcompiler
Version: 0.0.1a3
Summary: BuildCompiler is an open-source tool that bridges the Design and Build stages of the Synthetic Biology DBTL cycle
Home-page: https://github.com/MyersResearchGroup/BuildCompiler
Author: Gonzalo Vidal, Ryan Greer
Author-email: Gonzalo Vidal <gonzalo.vidalpena@colorado.edu>, Ryan Greer <ryan.greer@colorado.edu>
Maintainer: Ryan Greer
Maintainer-email: Ryan Greer <ryan.greer@colorado.edu>
License: MIT License
        
        Copyright (c) 2025 Genetic Logic 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
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/MyersResearchGroup/BuildCompiler
Project-URL: Bug Tracker, https://github.com/MyersResearchGroup/BuildCompiler/issues
Project-URL: Source, https://github.com/MyersResearchGroup/BuildCompiler
Keywords: SBOL,genetic,automation,build,synthetic biology
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sbol2
Requires-Dist: biopython
Requires-Dist: pydna
Provides-Extra: test
Requires-Dist: pytest<9,>=7; extra == "test"
Requires-Dist: pytest-cov[all]; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest<9,>=7; extra == "dev"
Requires-Dist: pytest-cov[all]; extra == "dev"
Requires-Dist: ruff>=0.14.0; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Provides-Extra: automation
Requires-Dist: pudupy; extra == "automation"
Requires-Dist: opentrons; extra == "automation"
Requires-Dist: SBOLInventory; extra == "automation"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: maintainer
Dynamic: requires-python

# BuildCompiler

[![Documentation Status](https://readthedocs.org/projects/buildcompiler/badge/?version=latest)](https://buildcompiler.readthedocs.io/en/latest/?badge=latest)

BuildCompiler is a Python compiler pipeline for synthetic biology build planning. It takes abstract SBOL designs and indexed biological inventory, then produces an executable build plan across domestication, MoClo assembly level 1, MoClo assembly level 2, transformation, and plating.

This repository is being refactored around a clean architecture. The existing codebase is useful as working evidence, especially the level-1 assembly path and SBOL digestion/ligation behavior, but the new implementation should not preserve old APIs, old import paths, or legacy module boundaries except the root package name `buildcompiler`.

## Why this exists

Designing a genetic construct is easier than building it in the lab. BuildCompiler should bridge that gap by compiling:

```text
abstract SBOL design + inventory -> build plan -> SBOL build artifacts -> PUDU JSON -> optional manual/OT-2 protocols
```

The Read the Docs site is available at [buildcompiler.readthedocs.io](https://buildcompiler.readthedocs.io/en/latest/) and is built from the Sphinx documentation in `docs/`.

The compiler should answer:

- Can this design be built from current inventory?
- Which plasmids, backbones, and reagents are required?
- Which missing engineered regions need level-1 assembly?
- Which missing promoter/RBS/CDS/terminator parts need domestication?
- Which route minimizes new build work?
- Which transformations and plating layouts follow from successful products?
- What actions should a user take next when a build is blocked?

## Core capabilities for v1

- Classify SBOL abstract designs into level-2, level-1, domestication, or unsupported work.
- Plan and execute a bounded full-build dependency loop.
- Support partial success: build what can be built, report what is missing, and retry after generated products are indexed.
- Optimize level-2 routes by searching feasible engineered-region orders and minimizing new level-1 plasmids.
- Optimize level-1 routes by minimizing new domestications.
- Produce cumulative and per-stage SBOL build artifacts.
- 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.

## Non-goals for v1

- Do not preserve legacy APIs or compatibility wrappers.
- Do not implement DNA extraction as a real stage; reserve `extracted` as a future material state.
- Do not run PUDU or Opentrons simulation by default.
- Do not make the build graph the scheduler in v1; it is reporting-only.
- Do not support variable-length level-1 constructs in v1.
- Do not silently approve sequence edits, reagent purchase, large combinatorial expansion, or large level-2 order search.

## Architecture at a glance

BuildCompiler should be organized as a compiler pipeline:

```text
api -> planning -> execution -> stages -> sbol/inventory/adapters -> reporting
```

Recommended package layout:

```text
src/buildcompiler/
  __init__.py

  api/
    __init__.py
    compiler.py
    options.py

  domain/
    __init__.py
    build_request.py
    build_result.py
    missing_input.py
    material_state.py
    plasmid.py
    reagent.py
    design.py
    approvals.py
    warnings.py

  planning/
    __init__.py
    classifier.py
    combinatorial.py
    full_build_planner.py
    validation.py

  execution/
    __init__.py
    context.py
    full_build_executor.py
    worklist.py
    stage_runner.py
    indexing.py

  stages/
    __init__.py
    domestication.py
    assembly_lvl1.py
    assembly_lvl2.py
    transformation.py
    plating.py

  sbol/
    __init__.py
    assembly.py
    domestication.py
    transformation.py
    documents.py
    identities.py
    resolver.py
    validation.py
    constants.py

  inventory/
    __init__.py
    synbiohub.py
    collection_indexer.py
    plasmid_index.py
    backbone_index.py
    reagent_index.py
    product_index.py
    compatibility.py
    selector.py

  adapters/
    __init__.py
    pudu/
      __init__.py
      assembly_json.py
      transformation_json.py
      plating_json.py
      protocol_generation.py
    opentrons/
      __init__.py
      simulation.py

  reporting/
    __init__.py
    build_graph.py
    summaries.py
    reports.py
    serialization.py

  errors.py
  logging.py
```

## Public API target

Keep the import root `buildcompiler`.

Primary usage should be stateful and object-based:

```python
from buildcompiler.api import BuildCompiler

compiler = BuildCompiler.from_synbiohub(
    collections=collections,
    sbh_registry=sbh_registry,
    auth_token=auth_token,
    sbol_doc=sbol_doc,
)

plan = compiler.plan(abstract_designs)
result = compiler.execute(plan)
```

A convenience wrapper may exist:

```python
from buildcompiler.api import full_build

result = full_build(
    abstract_designs=abstract_designs,
    collections=collections,
    sbh_registry=sbh_registry,
    auth_token=auth_token,
    sbol_doc=sbol_doc,
)
```

`BuildCompiler.__init__` should stay lightweight and dependency-injected. Automatic SynBioHub collection indexing belongs in `BuildCompiler.from_synbiohub(...)`.

## Local development

Recommended local workflow:

```bash
uv sync --all-groups
uv run ruff check .
uv run ruff format --check .
uv run pytest
```

If `uv` is not available, use a normal virtual environment and install editable dependencies:

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e '.[test]'
python -m pip install ruff
ruff check .
ruff format --check .
pytest
```

Automation-specific tests should be optional:

```bash
python -m pip install -e '.[automation,test]'
pytest tests/automation
```

## Container workflow

A Docker Compose workflow is recommended for reliable Codex and contributor development, but it does not need to block the first implementation PR.

Target commands after Docker support exists:

```bash
docker compose build
docker compose run --rm app ruff check .
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.

## Testing and quality checks

Default CI should run:

```bash
ruff check .
ruff format --check .
pytest tests/unit tests/stages tests/integration
```

Testing priorities:

1. Domain dataclasses and status semantics.
2. Planning and design classification.
3. Inventory indexing and compatibility selection.
4. Level-1 and level-2 route optimizers.
5. Domestication sequence-edit approval behavior.
6. Full-build bounded retry loop with mocked stages.
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.

## How ChatGPT and Codex should use these docs

- `PRODUCT.md` defines the product intent, v1 scope, and non-goals.
- `ARCHITECTURE.md` defines module boundaries and implementation contracts.
- `AGENT.md` defines how Codex should take tasks, report progress, and escalate decisions.
- `ADR-001.md` records the clean-architecture rewrite decision and its tradeoffs.
Codex should treat these files as the source of truth for implementation unless the user or ChatGPT explicitly revises them.

#### Running tests locally:
Run these bash commands to establish your SynBioHub account for collection access. These are saved in GitHub secrets for the automated test suite.

`export SBH_USERNAME=your_username`

`export SBH_PASSWORD=your_password`

Then run the tests with:

`uv run python -m unittest discover -s tests`

