API Reference

Public API

buildcompiler.api.compiler

Public BuildCompiler API skeleton.

class buildcompiler.api.compiler.BuildCompiler(inventory: 'Any' = None, sbol_document: 'Any' = None, planner: 'Any' = None, executor: 'Any' = None, adapters: 'Any' = None, options: 'BuildOptions' = <factory>)[source]

Bases: object

Parameters:

  • inventory (Any)

  • sbol_document (Any)

  • planner (Any)

  • executor (Any)

  • adapters (Any)

  • options (BuildOptions)

inventory: Any = None
sbol_document: Any = None
planner: Any = None
executor: Any = None
adapters: Any = None
options: BuildOptions
classmethod from_synbiohub(*, collections=None, sbh_registry=None, auth_token=None, sbol_doc=None, options=None, **kwargs)[source]
Parameters:

  • collections (list[str] | None)

  • sbh_registry (str | None)

  • auth_token (str | None)

  • sbol_doc (Any)

  • options (BuildOptions | None)

  • kwargs (Any)

Return type:

BuildCompiler

plan(abstract_designs, options=None)[source]
Parameters:
Return type:

Any

execute(plan, options=None)[source]
Parameters:
Return type:

Any

full_build(abstract_designs, options=None)[source]
Parameters:
Return type:

Any

buildcompiler.api.compiler.full_build(abstract_designs, *, inventory=None, sbol_document=None, planner=None, executor=None, adapters=None, options=None, collections=None, sbh_registry=None, auth_token=None, sbol_doc=None, **kwargs)[source]
Parameters:

  • abstract_designs (Any)

  • inventory (Any)

  • sbol_document (Any)

  • planner (Any)

  • executor (Any)

  • adapters (Any)

  • options (BuildOptions | None)

  • collections (list[str] | None)

  • sbh_registry (str | None)

  • auth_token (str | None)

  • sbol_doc (Any)

  • kwargs (Any)

Return type:

Any

buildcompiler.api.compiler.domestication(part, *, inventory, source_document, target_document=None, options=None)[source]

Run independent domestication stage(s) and return StageResult object(s).

Parameters:

  • part (ComponentDefinition | str | Sequence[ComponentDefinition | str])

  • inventory (Inventory)

  • source_document (Document)

  • target_document (Document | None)

  • options (BuildOptions | None)

Return type:

Any

buildcompiler.api.compiler.assembly_lvl1(design, *, inventory, source_document, target_document=None, options=None, constraints=None)[source]

Run one independent assembly level-1 stage and return a StageResult.

Parameters:

  • design (ComponentDefinition | str)

  • inventory (Inventory)

  • source_document (Document)

  • target_document (Document | None)

  • options (BuildOptions | None)

  • constraints (dict[str, Any] | None)

Return type:

Any

buildcompiler.api.compiler.assembly_lvl2(design, *, inventory, source_document, target_document=None, options=None, constraints=None)[source]

Run one independent assembly level-2 stage and return a StageResult.

Parameters:

  • design (ModuleDefinition | str)

  • inventory (Inventory)

  • source_document (Document)

  • target_document (Document | None)

  • options (BuildOptions | None)

  • constraints (dict[str, Any] | None)

Return type:

Any

buildcompiler.api.compiler.transformation(plasmid, *, source_document, target_document=None, options=None, chassis_identity=None, chassis_display_id=None)[source]

Run one independent transformation stage and return a StageResult.

Parameters:

  • plasmid (IndexedPlasmid)

  • source_document (Document)

  • target_document (Document | None)

  • options (BuildOptions | None)

  • chassis_identity (str | None)

  • chassis_display_id (str | None)

Return type:

Any

buildcompiler.api.options

Build options contracts for full_build configuration.

class buildcompiler.api.options.ProtocolMode(value)[source]

Bases: str, Enum

Protocol generation mode.

NONE = 'none'
MANUAL = 'manual'
AUTOMATED = 'automated'
class buildcompiler.api.options.CombinatorialOptions(max_variants: int = 256, allow_large_expansion: bool = False)[source]

Bases: object

Parameters:

  • max_variants (int)

  • allow_large_expansion (bool)

max_variants: int = 256
allow_large_expansion: bool = False
class buildcompiler.api.options.Lvl2SearchOptions(max_exhaustive_region_count: int = 4, allow_large_order_search: bool = False)[source]

Bases: object

Parameters:

  • max_exhaustive_region_count (int)

  • allow_large_order_search (bool)

max_exhaustive_region_count: int = 4
class buildcompiler.api.options.PlanningOptions(combinatorial: buildcompiler.api.options.CombinatorialOptions = <factory>, lvl2_search: buildcompiler.api.options.Lvl2SearchOptions = <factory>)[source]

Bases: object

Parameters:
combinatorial: CombinatorialOptions
class buildcompiler.api.options.ExecutionOptions(max_iterations: int = 5, continue_on_error: bool = False)[source]

Bases: object

Parameters:

  • max_iterations (int)

  • continue_on_error (bool)

max_iterations: int = 5
continue_on_error: bool = False
class buildcompiler.api.options.SelectionOptions(prefer_existing_collection_material: bool = True, prefer_higher_material_state: bool = True)[source]

Bases: object

Parameters:

  • prefer_existing_collection_material (bool)

  • prefer_higher_material_state (bool)

prefer_existing_collection_material: bool = True
prefer_higher_material_state: bool = True
class buildcompiler.api.options.ProtocolOptions(mode: buildcompiler.api.options.ProtocolMode = <ProtocolMode.NONE: 'none'>, simulate: bool = False, results_dir: str | pathlib.Path | None = None)[source]

Bases: object

Parameters:

  • mode (ProtocolMode)

  • simulate (bool)

  • results_dir (str | Path | None)

mode: ProtocolMode = 'none'
simulate: bool = False
results_dir: str | Path | None = None
class buildcompiler.api.options.ReportingOptions(include_detailed_report: bool = False, include_rejected_routes: bool = True, max_rejected_routes: int = 3)[source]

Bases: object

Parameters:

  • include_detailed_report (bool)

  • include_rejected_routes (bool)

  • max_rejected_routes (int)

include_detailed_report: bool = False
include_rejected_routes: bool = True
max_rejected_routes: int = 3
class buildcompiler.api.options.ApprovalOptions(approved_processes: set[str] = <factory>, approved_approval_ids: set[str] = <factory>, scope: Literal['run', 'persistent'] = 'run')[source]

Bases: object

Parameters:

  • approved_processes (set[str])

  • approved_approval_ids (set[str])

  • scope (Literal['run', 'persistent'])

approved_processes: set[str]
approved_approval_ids: set[str]
scope: Literal['run', 'persistent'] = 'run'
class buildcompiler.api.options.ReagentOptions(allow_reagent_purchase: bool = False, default_restriction_enzyme: str = 'BsaI', default_ligase: str = 'T4_DNA_ligase')[source]

Bases: object

Parameters:

  • allow_reagent_purchase (bool)

  • default_restriction_enzyme (str)

  • default_ligase (str)

allow_reagent_purchase: bool = False
default_restriction_enzyme: str = 'BsaI'
default_ligase: str = 'T4_DNA_ligase'
class buildcompiler.api.options.DomesticationOptions(allow_sequence_domestication_edits: bool = False)[source]

Bases: object

Parameters:

allow_sequence_domestication_edits (bool)

allow_sequence_domestication_edits: bool = False
class buildcompiler.api.options.TransformationOptions(enabled: bool = False, chassis_identity: str | None = None, chassis_display_id: str | None = None)[source]

Bases: object

Parameters:

  • enabled (bool)

  • chassis_identity (str | None)

  • chassis_display_id (str | None)

enabled: bool = False
chassis_identity: str | None = None
chassis_display_id: str | None = None
class buildcompiler.api.options.BuildOptions(planning: buildcompiler.api.options.PlanningOptions = <factory>, execution: buildcompiler.api.options.ExecutionOptions = <factory>, selection: buildcompiler.api.options.SelectionOptions = <factory>, protocol: buildcompiler.api.options.ProtocolOptions = <factory>, reporting: buildcompiler.api.options.ReportingOptions = <factory>, approvals: buildcompiler.api.options.ApprovalOptions = <factory>, reagents: buildcompiler.api.options.ReagentOptions = <factory>, domestication: buildcompiler.api.options.DomesticationOptions = <factory>, transformation: buildcompiler.api.options.TransformationOptions = <factory>)[source]

Bases: object

Parameters:
planning: PlanningOptions
execution: ExecutionOptions
selection: SelectionOptions
protocol: ProtocolOptions
reporting: ReportingOptions
approvals: ApprovalOptions
reagents: ReagentOptions
domestication: DomesticationOptions
transformation: TransformationOptions

Stages

buildcompiler.stages.assembly_lvl1

Thin lvl1 assembly stage orchestration.

class buildcompiler.stages.assembly_lvl1.AssemblyLvl1Stage(*, inventory, selector=None, assembly_service=None, options=None)[source]

Bases: object

Parameters:
run(request, *, source_document, target_document)[source]
Parameters:

  • request (BuildRequest)

  • source_document (Document)

  • target_document (Document)

Return type:

StageResult

buildcompiler.stages.assembly_lvl2

Thin lvl2 assembly stage orchestration.

class buildcompiler.stages.assembly_lvl2.AssemblyLvl2Stage(*, inventory, selector=None, assembly_service=None, options=None)[source]

Bases: object

Parameters:
run(request, *, source_document, target_document)[source]
Parameters:

  • request (BuildRequest)

  • source_document (Document)

  • target_document (Document)

Return type:

StageResult

buildcompiler.stages.domestication

Domestication stage orchestration.

class buildcompiler.stages.domestication.DomesticationStage(*, inventory, domestication_planner=None, domestication_service=None, options=None)[source]

Bases: object

Parameters:
run(request, *, source_document, target_document)[source]
Parameters:

  • request (BuildRequest)

  • source_document (Document)

  • target_document (Document)

Return type:

StageResult

buildcompiler.stages.transformation

Transformation stage orchestration.

class buildcompiler.stages.transformation.TransformationStage(*, transformation_service=None, options=None)[source]

Bases: object

Parameters:
run(plasmid_or_request, *, source_document=None, target_document=None)[source]
Parameters:
Return type:

StageResult

Planning

buildcompiler.planning.classifier

Design classification helpers for planning.

buildcompiler.planning.classifier.request_id_for(stage, source_identity, source_display_id, *, variant_index=None)[source]
Parameters:

  • stage (BuildStage)

  • source_identity (str)

  • source_display_id (str | None)

  • variant_index (int | None)

Return type:

str

buildcompiler.planning.classifier.classify_non_combinatorial(design)[source]
Parameters:

design (object)

Return type:

BuildRequest | UnsupportedPlanningRecord

buildcompiler.planning.combinatorial

buildcompiler.planning.combinatorial.expand_combinatorial_derivation(derivation, *, options)[source]
Parameters:

  • derivation (CombinatorialDerivation)

  • options (BuildOptions)

buildcompiler.planning.domestication

Deterministic domestication planning helpers.

class buildcompiler.planning.domestication.SequenceEditProposal(source_identity: 'str', enzyme_name: 'str', site_sequence: 'str', position: 'int', original_sequence: 'str', proposed_sequence: 'str', reason: 'str', approved: 'bool' = False)[source]

Bases: object

Parameters:

  • source_identity (str)

  • enzyme_name (str)

  • site_sequence (str)

  • position (int)

  • original_sequence (str)

  • proposed_sequence (str)

  • reason (str)

  • approved (bool)

source_identity: str
enzyme_name: str
site_sequence: str
position: int
original_sequence: str
proposed_sequence: str
reason: str
approved: bool = False
class buildcompiler.planning.domestication.DomesticationPlan(part_identity: 'str', part_display_id: 'str | None', part_role: 'str', backbone_identity: 'str | None' = None, restriction_enzyme_name: 'str' = 'BsaI', ligase_name: 'str' = 'T4_DNA_ligase', sequence_edit_proposals: 'list[SequenceEditProposal]' = <factory>, warnings: 'list[BuildWarning]' = <factory>)[source]

Bases: object

Parameters:

  • part_identity (str)

  • part_display_id (str | None)

  • part_role (str)

  • backbone_identity (str | None)

  • restriction_enzyme_name (str)

  • ligase_name (str)

  • sequence_edit_proposals (list[SequenceEditProposal])

  • warnings (list[BuildWarning])

part_identity: str
part_display_id: str | None
part_role: str
backbone_identity: str | None = None
restriction_enzyme_name: str = 'BsaI'
ligase_name: str = 'T4_DNA_ligase'
sequence_edit_proposals: list[SequenceEditProposal]
warnings: list[BuildWarning]
class buildcompiler.planning.domestication.DomesticationPlanner[source]

Bases: object

Pure planner for domestication requirements for a single part.

plan(part_component)[source]
Parameters:

part_component (ComponentDefinition)

Return type:

DomesticationPlan

buildcompiler.planning.domestication.select_deterministic_flanking_sequence(*, source_sequence, flank_length, forbidden_sites=('GGTCTC', 'GAGACC'))[source]

TODO: choose deterministic domestication flanks that avoid forbidden sites.

Parameters:

  • source_sequence (str)

  • flank_length (int)

  • forbidden_sites (tuple[str, ...])

Return type:

str

buildcompiler.planning.full_build_planner

Pure full-build planner orchestration.

class buildcompiler.planning.full_build_planner.FullBuildPlanner(*, options=None, resolver=None)[source]

Bases: object

Parameters:
plan(abstract_designs, *, options=None)[source]
Parameters:

  • abstract_designs (Iterable[object])

  • options (BuildOptions | None)

Return type:

BuildPlan

buildcompiler.planning.models

Planning contracts for full-build planning output.

class buildcompiler.planning.models.UnsupportedPlanningRecord(source_identity: str, source_display_id: str | None, source_kind: buildcompiler.domain.design.DesignKind, reason: str, metadata: dict[str, typing.Any] = <factory>)[source]

Bases: object

Parameters:

  • source_identity (str)

  • source_display_id (str | None)

  • source_kind (DesignKind)

  • reason (str)

  • metadata (dict[str, Any])

source_identity: str
source_display_id: str | None
source_kind: DesignKind
reason: str
metadata: dict[str, Any]
class buildcompiler.planning.models.BuildPlan(lvl2_requests: list[buildcompiler.domain.build_request.BuildRequest] = <factory>, lvl1_requests: list[buildcompiler.domain.build_request.BuildRequest] = <factory>, domestication_requests: list[buildcompiler.domain.build_request.BuildRequest] = <factory>, unsupported: list[buildcompiler.planning.models.UnsupportedPlanningRecord] = <factory>, warnings: list[buildcompiler.domain.warnings.BuildWarning] = <factory>)[source]

Bases: object

Parameters:
lvl2_requests: list[BuildRequest]
lvl1_requests: list[BuildRequest]
domestication_requests: list[BuildRequest]
unsupported: list[UnsupportedPlanningRecord]
warnings: list[BuildWarning]

buildcompiler.planning.validation

Deterministic validation helpers for level-1 designs.

buildcompiler.planning.validation.classify_part_role(component_definition)[source]
Parameters:

component_definition (ComponentDefinition)

Return type:

str | None

buildcompiler.planning.validation.validate_lvl1_cardinality(component_definition)[source]
Parameters:

component_definition (ComponentDefinition)

Return type:

tuple[bool, list[BuildWarning]]

buildcompiler.planning.validation.ordered_lvl1_parts(component_definition)[source]
Parameters:

component_definition (ComponentDefinition)

Return type:

tuple[list[str], list[BuildWarning]]

Inventory

buildcompiler.inventory.compatibility

Deterministic compatibility route models and score ordering.

class buildcompiler.inventory.compatibility.RouteScore(missing_required_products: 'int' = 0, missing_domestications: 'int' = 0, missing_lvl1_plasmids: 'int' = 0, generated_or_planned_materials: 'int' = 0, lower_material_state_penalty: 'int' = 0, constraint_violations: 'int' = 0, total_assemblies: 'int' = 0, identity_tiebreak: 'tuple[str, ...]' = ())[source]

Bases: object

Parameters:

  • missing_required_products (int)

  • missing_domestications (int)

  • missing_lvl1_plasmids (int)

  • generated_or_planned_materials (int)

  • lower_material_state_penalty (int)

  • constraint_violations (int)

  • total_assemblies (int)

  • identity_tiebreak (tuple[str, ...])

missing_required_products: int = 0
missing_domestications: int = 0
missing_lvl1_plasmids: int = 0
generated_or_planned_materials: int = 0
lower_material_state_penalty: int = 0
constraint_violations: int = 0
total_assemblies: int = 0
identity_tiebreak: tuple[str, ...] = ()
sort_key()[source]

Lower sort key is a better route.

Return type:

tuple[int, int, int, int, int, int, int, tuple[str, …]]

class buildcompiler.inventory.compatibility.Lvl1Route(request_id: 'str', part_identities: 'tuple[str, ...]', selected_part_plasmids: 'tuple[IndexedPlasmid, ...]', missing_part_identities: 'tuple[str, ...]', backbone: 'IndexedBackbone | None', score: 'RouteScore')[source]

Bases: object

Parameters:

  • request_id (str)

  • part_identities (tuple[str, ...])

  • selected_part_plasmids (tuple[IndexedPlasmid, ...])

  • missing_part_identities (tuple[str, ...])

  • backbone (IndexedBackbone | None)

  • score (RouteScore)

request_id: str
part_identities: tuple[str, ...]
selected_part_plasmids: tuple[IndexedPlasmid, ...]
missing_part_identities: tuple[str, ...]
backbone: IndexedBackbone | None
score: RouteScore
class buildcompiler.inventory.compatibility.Lvl2Route(request_id: 'str', region_order: 'tuple[str, ...]', selected_lvl1_plasmids: 'tuple[IndexedPlasmid, ...]', missing_region_identities: 'tuple[str, ...]', backbone: 'IndexedBackbone | None', score: 'RouteScore')[source]

Bases: object

Parameters:

  • request_id (str)

  • region_order (tuple[str, ...])

  • selected_lvl1_plasmids (tuple[IndexedPlasmid, ...])

  • missing_region_identities (tuple[str, ...])

  • backbone (IndexedBackbone | None)

  • score (RouteScore)

request_id: str
region_order: tuple[str, ...]
selected_lvl1_plasmids: tuple[IndexedPlasmid, ...]
missing_region_identities: tuple[str, ...]
backbone: IndexedBackbone | None
score: RouteScore
class buildcompiler.inventory.compatibility.RouteSelection(selected: 'Lvl1Route | Lvl2Route | None', rejected: 'tuple[Lvl1Route | Lvl2Route, ...]' = ())[source]

Bases: object

Parameters:
selected: Lvl1Route | Lvl2Route | None
rejected: tuple[Lvl1Route | Lvl2Route, ...] = ()

buildcompiler.inventory.inventory

Normalized inventory facade with eager deterministic indexes.

class buildcompiler.inventory.inventory.Inventory(*, plasmids=None, backbones=None, reagents=None)[source]

Bases: object

Parameters:
find_single_part_plasmids(part_identity, *, antibiotic=None)[source]
Parameters:

  • part_identity (str)

  • antibiotic (str | None)

Return type:

list[IndexedPlasmid]

find_lvl1_region_plasmids(region_identity, *, min_material_state=MaterialState.PLANNED)[source]
Parameters:
Return type:

list[IndexedPlasmid]

find_backbone(*, fusion_sites=None, antibiotic=None, stage=None)[source]
Parameters:

  • fusion_sites (tuple[str, ...] | None)

  • antibiotic (str | None)

  • stage (BuildStage | None)

Return type:

IndexedBackbone | None

find_restriction_enzyme(name)[source]
Parameters:

name (str)

Return type:

IndexedReagent | None

find_ligase(preferred=None)[source]
Parameters:

preferred (str | None)

Return type:

IndexedReagent | None

add_generated_product(product)[source]
Parameters:

product (IndexedPlasmid)

Return type:

None

buildcompiler.inventory.selector

Deterministic compatibility selector for lvl1/lvl2 route selection.

class buildcompiler.inventory.selector.CompatibilitySelector(inventory, *, options=None)[source]

Bases: object

Parameters:
select_lvl1_route(*, request_id, part_identities, constraints=None)[source]
Parameters:

  • request_id (str)

  • part_identities (Sequence[str])

  • constraints (Mapping[str, Any] | None)

Return type:

RouteSelection

select_lvl2_route(*, request_id, region_identities, constraints=None)[source]
Parameters:

  • request_id (str)

  • region_identities (Sequence[str])

  • constraints (Mapping[str, Any] | None)

Return type:

RouteSelection

SBOL helpers

buildcompiler.sbol.assembly

SBOL assembly service wrapping legacy Golden Gate behavior.

class buildcompiler.sbol.assembly.AssemblyJob(stage, product_identity, product_display_id, part_plasmids, backbone, restriction_enzyme, ligase, source_document, target_document, include_extracted_parts=False)[source]

Bases: object

Normalized assembly inputs plus source/target SBOL documents.

Parameters:
stage: BuildStage
product_identity: str
product_display_id: str
part_plasmids: list[IndexedPlasmid]
backbone: IndexedBackbone
restriction_enzyme: IndexedReagent
ligase: IndexedReagent
source_document: Document
target_document: Document
include_extracted_parts: bool = False
class buildcompiler.sbol.assembly.AssemblySbolResult(products, stage_document, activity_identity, logs=<factory>)[source]

Bases: object

Assembly output contract: normalized products plus stage document.

Parameters:

  • products (list[IndexedPlasmid])

  • stage_document (Document)

  • activity_identity (str)

  • logs (list[str])

products: list[IndexedPlasmid]
stage_document: Document
activity_identity: str
logs: list[str]
class buildcompiler.sbol.assembly.AssemblyService[source]

Bases: object

Service wrapper that preserves legacy assembly internals behind normalized contracts.

run(job)[source]
Parameters:

job (AssemblyJob)

Return type:

AssemblySbolResult

buildcompiler.sbol.domestication

SBOL domestication service.

class buildcompiler.sbol.domestication.DomesticationJob(part_identity: 'str', part_display_id: 'str | None', part_component: 'Any', backbone: 'IndexedBackbone', restriction_enzyme: 'IndexedReagent', ligase: 'IndexedReagent', source_document: 'Any', target_document: 'Any', part_role: 'str | None' = None, fusion_site_sequences: 'tuple[str, str] | None' = None, fusion_site_names: 'tuple[str, str] | None' = None, sequence_edit_proposals: 'list[Any]' = <factory>)[source]

Bases: object

Parameters:

  • part_identity (str)

  • part_display_id (str | None)

  • part_component (Any)

  • backbone (IndexedBackbone)

  • restriction_enzyme (IndexedReagent)

  • ligase (IndexedReagent)

  • source_document (Any)

  • target_document (Any)

  • part_role (str | None)

  • fusion_site_sequences (tuple[str, str] | None)

  • fusion_site_names (tuple[str, str] | None)

  • sequence_edit_proposals (list[Any])

part_identity: str
part_display_id: str | None
part_component: Any
backbone: IndexedBackbone
restriction_enzyme: IndexedReagent
ligase: IndexedReagent
source_document: Any
target_document: Any
part_role: str | None = None
fusion_site_sequences: tuple[str, str] | None = None
fusion_site_names: tuple[str, str] | None = None
sequence_edit_proposals: list[Any]
class buildcompiler.sbol.domestication.DomesticationSbolResult(product: 'IndexedPlasmid', stage_document: 'Any', artifacts: 'dict[str, Any]' = <factory>, logs: 'list[str]' = <factory>)[source]

Bases: object

Parameters:

  • product (IndexedPlasmid)

  • stage_document (Any)

  • artifacts (dict[str, Any])

  • logs (list[str])

product: IndexedPlasmid
stage_document: Any
artifacts: dict[str, Any]
logs: list[str]
class buildcompiler.sbol.domestication.DomesticationService[source]

Bases: object

run(job)[source]
Parameters:

job (DomesticationJob)

Return type:

DomesticationSbolResult

buildcompiler.sbol.resolver

SBOL document resolver with deterministic pull policy.

class buildcompiler.sbol.resolver.PullPolicy(value)[source]

Bases: str, Enum

Resolver behavior for remote pull attempts.

NEVER = 'never'
MISSING_ONLY = 'missing_only'
ALWAYS_REFRESH = 'always_refresh'
class buildcompiler.sbol.resolver.SbolResolver(document, *, pull_policy=PullPolicy.MISSING_ONLY, pull_client=None)[source]

Bases: object

Resolve SBOL objects by identity from a local document with optional pull fallback.

Parameters:

  • document (sbol2.Document)

  • pull_policy (PullPolicy)

  • pull_client (Callable[[str], Any] | None)

maybe_pull(identity)[source]
Parameters:

identity (str)

Return type:

Any | None

get_component(identity)[source]
Parameters:

identity (str)

Return type:

ComponentDefinition

get_module(identity)[source]
Parameters:

identity (str)

Return type:

ModuleDefinition

get_combinatorial_derivation(identity)[source]
Parameters:

identity (str)

Return type:

CombinatorialDerivation

get_implementation(identity)[source]
Parameters:

identity (str)

Return type:

Implementation

buildcompiler.sbol.transformation

SBOL transformation service.

class buildcompiler.sbol.transformation.TransformationJob(plasmid: 'IndexedPlasmid', chassis_identity: 'str', chassis_display_id: 'str', source_document: 'Any', target_document: 'Any')[source]

Bases: object

Parameters:

  • plasmid (IndexedPlasmid)

  • chassis_identity (str)

  • chassis_display_id (str)

  • source_document (Any)

  • target_document (Any)

plasmid: IndexedPlasmid
chassis_identity: str
chassis_display_id: str
source_document: Any
target_document: Any
class buildcompiler.sbol.transformation.TransformationSbolResult(product: 'IndexedStrain', stage_document: 'Any', activity_identity: 'str', artifacts: 'dict[str, Any]' = <factory>, logs: 'list[str]' = <factory>)[source]

Bases: object

Parameters:

  • product (IndexedStrain)

  • stage_document (Any)

  • activity_identity (str)

  • artifacts (dict[str, Any])

  • logs (list[str])

product: IndexedStrain
stage_document: Any
activity_identity: str
artifacts: dict[str, Any]
logs: list[str]
class buildcompiler.sbol.transformation.TransformationService[source]

Bases: object

Create SBOL records for transforming a chassis with one plasmid.

run(job)[source]
Parameters:

job (TransformationJob)

Return type:

TransformationSbolResult

Domain models

buildcompiler.domain.approvals

Approval contracts for expected gated processes.

class buildcompiler.domain.approvals.ApprovalStatus(value)[source]

Bases: str, Enum

Minimal approval state used by RequiredApproval.

REQUIRED = 'required'
APPROVED = 'approved'
class buildcompiler.domain.approvals.RequiredApproval(status, process, reason, metadata=<factory>)[source]

Bases: object

Approval record for a process required to proceed.

Parameters:

  • status (ApprovalStatus)

  • process (str)

  • reason (str)

  • metadata (dict[str, Any])

status: ApprovalStatus
process: str
reason: str
metadata: dict[str, Any]

buildcompiler.domain.build_request

Build request contract dataclass.

class buildcompiler.domain.build_request.BuildRequest(id, stage, source_identity, source_display_id, source_kind, parent_group=None, variant_index=None, constraints=<factory>)[source]

Bases: object

Planner-produced request for a single stage/source item.

Parameters:

  • id (str)

  • stage (BuildStage)

  • source_identity (str)

  • source_display_id (str | None)

  • source_kind (DesignKind)

  • parent_group (str | None)

  • variant_index (int | None)

  • constraints (dict[str, Any])

id: str
stage: BuildStage
source_identity: str
source_display_id: str | None
source_kind: DesignKind
parent_group: str | None = None
variant_index: int | None = None
constraints: dict[str, Any]

buildcompiler.domain.build_result

Stage/full-build result contracts.

class buildcompiler.domain.build_result.StageResult(id, stage, status, request_ids=<factory>, products=<factory>, missing_inputs=<factory>, required_approvals=<factory>, warnings=<factory>, sbol_document=None, json_intermediate=None, protocol_artifacts=<factory>, logs=<factory>)[source]

Bases: object

Output contract from a single stage invocation.

Parameters:
id: str
stage: BuildStage
status: StageStatus
request_ids: list[str]
products: list[IndexedPlasmid | IndexedStrain]
missing_inputs: list[MissingBuildInput]
required_approvals: list[RequiredApproval]
warnings: list[BuildWarning]
sbol_document: Any | None = None
json_intermediate: dict[str, Any] | list[Any] | None = None
protocol_artifacts: dict[str, Any]
logs: list[str]
class buildcompiler.domain.build_result.FullBuildResult(status, plan, build_document, stage_results=<factory>, graph=None, final_products=<factory>, missing_inputs=<factory>, required_approvals=<factory>, warnings=<factory>, summary=None, report=None)[source]

Bases: object

Aggregate full-build output contract.

Neighboring contracts (plan/graph/summary/report) are intentionally typed conservatively until their milestone implementations are added.

Parameters:
status: BuildStatus
plan: Any
build_document: Any
stage_results: list[StageResult]
graph: Any = None
final_products: list[IndexedPlasmid | IndexedStrain]
missing_inputs: list[MissingBuildInput]
required_approvals: list[RequiredApproval]
warnings: list[BuildWarning]
summary: Any = None
report: Any | None = None

buildcompiler.domain.build_stage

Build stage enum contracts.

class buildcompiler.domain.build_stage.BuildStage(value)[source]

Bases: str, Enum

Planned v1 build stages for full-build execution.

DOMESTICATION = 'domestication'
ASSEMBLY_LVL1 = 'assembly_lvl1'
ASSEMBLY_LVL2 = 'assembly_lvl2'
TRANSFORMATION = 'transformation'
PLATING = 'plating'

buildcompiler.domain.design

Design identity/type contracts.

class buildcompiler.domain.design.DesignKind(value)[source]

Bases: str, Enum

Supported SBOL design source kinds for build requests.

COMPONENT_DEFINITION = 'component_definition'
MODULE_DEFINITION = 'module_definition'
COMBINATORIAL_DERIVATION = 'combinatorial_derivation'
UNSUPPORTED = 'unsupported'

buildcompiler.domain.material_state

Material lifecycle states used across stages.

class buildcompiler.domain.material_state.MaterialState(value)[source]

Bases: str, Enum

Normalized lifecycle states for build materials.

PLANNED = 'planned'
GENERATED = 'generated'
ASSEMBLED = 'assembled'
TRANSFORMED = 'transformed'
PLATED = 'plated'

buildcompiler.domain.missing_input

Missing input/blocker contracts.

class buildcompiler.domain.missing_input.MissingBuildInput(source_stage, source_design_identity, missing_identity, missing_display_id, missing_kind, required_stage, reason, candidates_tried=<factory>)[source]

Bases: object

Expected blocker produced when build inputs are unavailable.

Parameters:

  • source_stage (BuildStage)

  • source_design_identity (str)

  • missing_identity (str)

  • missing_display_id (str | None)

  • missing_kind (Literal['engineered_region', 'promoter', 'rbs', 'cds', 'terminator', 'backbone', 'restriction_enzyme', 'ligase', 'reagent', 'chassis'])

  • required_stage (BuildStage | Literal['fatal'])

  • reason (str)

  • candidates_tried (list[str])

source_stage: BuildStage
source_design_identity: str
missing_identity: str
missing_display_id: str | None
missing_kind: Literal['engineered_region', 'promoter', 'rbs', 'cds', 'terminator', 'backbone', 'restriction_enzyme', 'ligase', 'reagent', 'chassis']
required_stage: BuildStage | Literal['fatal']
reason: str
candidates_tried: list[str]

buildcompiler.domain.plasmid

Normalized plasmid/backbone records.

class buildcompiler.domain.plasmid.IndexedPlasmid(identity, display_id=None, name=None, state=MaterialState.PLANNED, roles=<factory>, metadata=<factory>, sbol_component=None)[source]

Bases: object

Inventory/index record for a plasmid-like material.

Parameters:

  • identity (str)

  • display_id (str | None)

  • name (str | None)

  • state (MaterialState)

  • roles (list[str])

  • metadata (dict[str, Any])

  • sbol_component (Any | None)

identity: str
display_id: str | None = None
name: str | None = None
state: MaterialState = 'planned'
roles: list[str]
metadata: dict[str, Any]
sbol_component: Any | None = None
class buildcompiler.domain.plasmid.IndexedBackbone(identity, display_id=None, name=None, metadata=<factory>, sbol_component=None)[source]

Bases: object

Inventory/index record for a backbone material.

Parameters:

  • identity (str)

  • display_id (str | None)

  • name (str | None)

  • metadata (dict[str, Any])

  • sbol_component (Any | None)

identity: str
display_id: str | None = None
name: str | None = None
metadata: dict[str, Any]
sbol_component: Any | None = None
class buildcompiler.domain.plasmid.IndexedStrain(identity, display_id=None, name=None, state=MaterialState.TRANSFORMED, roles=<factory>, metadata=<factory>, sbol_module=None)[source]

Bases: object

Inventory/index record for a transformed strain-like material.

Parameters:

  • identity (str)

  • display_id (str | None)

  • name (str | None)

  • state (MaterialState)

  • roles (list[str])

  • metadata (dict[str, Any])

  • sbol_module (Any | None)

identity: str
display_id: str | None = None
name: str | None = None
state: MaterialState = 'transformed'
roles: list[str]
metadata: dict[str, Any]
sbol_module: Any | None = None

buildcompiler.domain.reagent

Normalized reagent record contracts.

class buildcompiler.domain.reagent.IndexedReagent(identity, display_id=None, name=None, reagent_type=None, metadata=<factory>)[source]

Bases: object

Inventory/index record for reagents.

Parameters:

  • identity (str)

  • display_id (str | None)

  • name (str | None)

  • reagent_type (str | None)

  • metadata (dict[str, Any])

identity: str
display_id: str | None = None
name: str | None = None
reagent_type: str | None = None
metadata: dict[str, Any]

buildcompiler.domain.status

Status enums and contract-level semantics helpers.

class buildcompiler.domain.status.StageStatus(value)[source]

Bases: str, Enum

Status for a single stage result.

BLOCKED means expected inputs or approvals can unblock this stage later. FAILED means the request cannot proceed without changing design/options/ collections/approval state.

SUCCESS = 'success'
PARTIAL_SUCCESS = 'partial_success'
BLOCKED = 'blocked'
FAILED = 'failed'
class buildcompiler.domain.status.BuildStatus(value)[source]

Bases: str, Enum

Status for full-build aggregate results.

SUCCESS = 'success'
PARTIAL_SUCCESS = 'partial_success'
FAILED = 'failed'

buildcompiler.domain.warnings

Domain warning contracts.

class buildcompiler.domain.warnings.BuildWarning(code, message, stage=None, source_identity=None, metadata=<factory>)[source]

Bases: object

Structured non-fatal warning for planning/execution/reporting.

Parameters:

  • code (str)

  • message (str)

  • stage (BuildStage | None)

  • source_identity (str | None)

  • metadata (dict[str, Any])

code: str
message: str
stage: BuildStage | None = None
source_identity: str | None = None
metadata: dict[str, Any]

Execution

buildcompiler.execution.context

Execution context contract for full-build orchestration.

class buildcompiler.execution.context.BuildContext(sbol: 'SbolResolver', inventory: 'Inventory', build_document: 'Any', options: 'Any', adapters: 'Any' = None, graph: 'Any' = None, logger: 'Any' = None)[source]

Bases: object

Parameters:

  • sbol (SbolResolver)

  • inventory (Inventory)

  • build_document (Any)

  • options (Any)

  • adapters (Any)

  • graph (Any)

  • logger (Any)

sbol: SbolResolver
inventory: Inventory
build_document: Any
options: Any
adapters: Any = None
graph: Any = None
logger: Any = None

buildcompiler.execution.executor

Bounded fixed-point full-build executor.

class buildcompiler.execution.executor.FullBuildExecutor(*, context, lvl2_stage=None, lvl1_stage=None, domestication_stage=None, transformation_stage=None, plating_stage=None)[source]

Bases: object

Parameters:

  • context (BuildContext)

  • lvl2_stage (Any | None)

  • lvl1_stage (Any | None)

  • domestication_stage (Any | None)

  • transformation_stage (Any | None)

  • plating_stage (Any | None)

classmethod from_dependencies(*, inventory, sbol_document, options, adapters=None, graph=None, logger=None, **stage_overrides)[source]
Parameters:

  • inventory (Inventory)

  • sbol_document (Any)

  • options (BuildOptions)

  • adapters (Any)

  • graph (Any)

  • logger (Any)

  • stage_overrides (Any)

Return type:

FullBuildExecutor

execute(plan, *, options=None)[source]
Parameters:
Return type:

FullBuildResult

Adapters

buildcompiler.adapters.opentrons.simulation

Optional Opentrons simulation boundary adapter.

exception buildcompiler.adapters.opentrons.simulation.OptionalAutomationDependencyError[source]

Bases: ImportError

Raised when optional automation dependency is unavailable.

class buildcompiler.adapters.opentrons.simulation.SimulationResult(ran: 'bool', logs: 'list[str]' = <factory>, metadata: 'dict[str, object]' = <factory>)[source]

Bases: object

Parameters:

  • ran (bool)

  • logs (list[str])

  • metadata (dict[str, object])

ran: bool
logs: list[str]
metadata: dict[str, object]
class buildcompiler.adapters.opentrons.simulation.OpentronsSimulationAdapter[source]

Bases: object

simulate(protocol_source, *, options)[source]
Parameters:
Return type:

SimulationResult

buildcompiler.adapters.protocols

Protocol artifact boundaries for optional file output.

class buildcompiler.adapters.protocols.ProtocolArtifact(kind: 'str', path: 'Path | None' = None, content: 'str | dict[str, object] | list[dict[str, object]] | None' = None, metadata: 'dict[str, object]' = <factory>)[source]

Bases: object

Parameters:

  • kind (str)

  • path (Path | None)

  • content (str | dict[str, object] | list[dict[str, object]] | None)

  • metadata (dict[str, object])

kind: str
path: Path | None = None
content: str | dict[str, object] | list[dict[str, object]] | None = None
metadata: dict[str, object]
buildcompiler.adapters.protocols.maybe_write_protocol_artifacts(*, payloads, options, basename='buildcompiler_protocol')[source]

Return in-memory protocol payloads and optionally write them to disk.

Parameters:
Return type:

dict[str, ProtocolArtifact]

buildcompiler.adapters.pudu.assembly_json

In-memory adapter for compiler-level PUDU assembly JSON payloads.

buildcompiler.adapters.pudu.assembly_json.assembly_route_to_pudu_json(*, product_identity, part_plasmids, backbone, restriction_enzyme)[source]

Adapt a selected lvl1 route into legacy-compatible assembly JSON keys.

Parameters:
Return type:

dict[str, object]

buildcompiler.adapters.pudu.assembly_json.assembly_routes_to_pudu_json(*, product_identities, part_plasmid_routes, backbones, restriction_enzymes)[source]

Batch helper for deterministic in-memory assembly JSON payloads.

Parameters:
Return type:

list[dict[str, object]]

buildcompiler.adapters.pudu.assembly_json.legacy_assembly_route_to_pudu_json(*, product_plasmid, part_plasmids, backbone, restriction_enzyme)[source]

Adapt legacy Plasmid route objects into PUDU assembly JSON.

This path intentionally uses route inputs rather than scraping the generated SBOL product document. The product SBOL document may omit source plasmid definitions, but the route always knows the product plasmid, backbone plasmid, selected part plasmids, and restriction enzyme implementation.

Parameters:

  • product_plasmid (Any)

  • part_plasmids (Sequence[Any])

  • backbone (Any)

  • restriction_enzyme (Any)

Return type:

dict[str, object]

buildcompiler.adapters.pudu.assembly_json.legacy_assembly_routes_to_pudu_json(*, product_plasmids, part_plasmid_routes, backbones, restriction_enzymes)[source]

Batch helper for deterministic legacy PUDU assembly JSON payloads.

Parameters:

  • product_plasmids (Sequence[Any])

  • part_plasmid_routes (Sequence[Sequence[Any]])

  • backbones (Sequence[Any])

  • restriction_enzymes (Sequence[Any])

Return type:

list[dict[str, object]]

buildcompiler.adapters.pudu.assembly_json.domestication_artifact_to_pudu_json(artifact)[source]

Adapt one domestication artifact into PUDU assembly-style JSON.

Parameters:

artifact (dict[str, Any])

Return type:

dict[str, object]

buildcompiler.adapters.pudu.assembly_json.domestication_artifacts_to_pudu_json(artifacts)[source]

Batch helper for domestication PUDU assembly-style JSON payloads.

Parameters:

artifacts (Sequence[dict[str, Any]])

Return type:

list[dict[str, object]]

buildcompiler.adapters.pudu.assembly_json.write_assembly_pudu_input_json(payload, output_path)[source]

Write a deterministic PUDU assembly input JSON file.

Parameters:

  • payload (dict[str, object] | Sequence[dict[str, object]])

  • output_path (str | Path)

Return type:

Path

buildcompiler.adapters.pudu.plating_json

In-memory adapter for compiler-level PUDU plating JSON payloads.

buildcompiler.adapters.pudu.plating_json.plating_to_pudu_json(*, bacterium_locations, advanced_parameters=None)[source]

Adapt plating records into PUDU’s plating input JSON.

PUDU expects thermocycler source wells as keys and transformed construct identifiers as values, wrapped under bacterium_locations.

Parameters:

  • bacterium_locations (Mapping[str, str | list[str]])

  • advanced_parameters (Mapping[str, object] | None)

Return type:

dict[str, object]

buildcompiler.adapters.pudu.transformation_json

In-memory adapter for compiler-level PUDU transformation JSON payloads.

buildcompiler.adapters.pudu.transformation_json.transformation_to_pudu_json(*, strain_identity, chassis_identity, plasmids)[source]

Adapt a transformation record into legacy-compatible PUDU JSON keys.

Parameters:

  • strain_identity (str)

  • chassis_identity (str)

  • plasmids (Sequence[IndexedPlasmid | str])

Return type:

dict[str, object]

buildcompiler.adapters.pudu.transformation_json.transformations_to_pudu_json(*, strain_identities, chassis_identities, plasmid_sets)[source]

Batch helper for deterministic in-memory transformation JSON payloads.

Parameters:

  • strain_identities (Sequence[str])

  • chassis_identities (Sequence[str])

  • plasmid_sets (Sequence[Sequence[IndexedPlasmid | str]])

Return type:

list[dict[str, object]]

buildcompiler.adapters.pudu.transformation_json.plasmid_locations_to_pudu_json(plasmids, *, wells=None)[source]

Create PUDU’s assembly-output plasmid location map.

PUDU’s transformation protocol optionally consumes the transformation_input.json emitted by its assembly simulation. The shape is {"plasmid_uri": ["A1"]}, where each value is a list because one plasmid may be available in multiple source wells.

Parameters:

  • plasmids (Sequence[IndexedPlasmid | str])

  • wells (Sequence[str] | None)

Return type:

dict[str, list[str]]

Reporting

buildcompiler.reporting.graph

class buildcompiler.reporting.graph.BuildGraphNode(id: 'str', kind: 'str', label: 'str | None' = None, metadata: 'dict[str, Any]' = <factory>)[source]

Bases: object

Parameters:

  • id (str)

  • kind (str)

  • label (str | None)

  • metadata (dict[str, Any])

id: str
kind: str
label: str | None = None
metadata: dict[str, Any]
class buildcompiler.reporting.graph.BuildGraphEdge(source: 'str', target: 'str', relationship: 'str', metadata: 'dict[str, Any]' = <factory>)[source]

Bases: object

Parameters:

  • source (str)

  • target (str)

  • relationship (str)

  • metadata (dict[str, Any])

source: str
target: str
relationship: str
metadata: dict[str, Any]
class buildcompiler.reporting.graph.BuildGraph(nodes: 'list[BuildGraphNode]' = <factory>, edges: 'list[BuildGraphEdge]' = <factory>)[source]

Bases: object

Parameters:
nodes: list[BuildGraphNode]
edges: list[BuildGraphEdge]
add_node(node)[source]
Parameters:

node (BuildGraphNode)

Return type:

None

add_edge(edge)[source]
Parameters:

edge (BuildGraphEdge)

Return type:

None

to_dict()[source]
Return type:

dict[str, object]

summary()[source]
Return type:

dict[str, object]

buildcompiler.reporting.graph.build_graph(result)[source]
Parameters:

result (FullBuildResult)

Return type:

BuildGraph

buildcompiler.reporting.report

class buildcompiler.reporting.report.StageReportSection(stage: 'str', status: 'str', request_ids: 'list[str]', product_count: 'int', missing_input_count: 'int', approval_count: 'int', warning_count: 'int', logs: 'list[str]' = <factory>)[source]

Bases: object

Parameters:

  • stage (str)

  • status (str)

  • request_ids (list[str])

  • product_count (int)

  • missing_input_count (int)

  • approval_count (int)

  • warning_count (int)

  • logs (list[str])

stage: str
status: str
request_ids: list[str]
product_count: int
missing_input_count: int
approval_count: int
warning_count: int
logs: list[str]
class buildcompiler.reporting.report.RouteReport(source_stage_result_id: 'str', selected: 'bool', route: 'dict[str, Any]')[source]

Bases: object

Parameters:

  • source_stage_result_id (str)

  • selected (bool)

  • route (dict[str, Any])

source_stage_result_id: str
selected: bool
route: dict[str, Any]
class buildcompiler.reporting.report.RecommendedAction(code: 'str', message: 'str', metadata: 'dict[str, Any]' = <factory>)[source]

Bases: object

Parameters:

  • code (str)

  • message (str)

  • metadata (dict[str, Any])

code: str
message: str
metadata: dict[str, Any]
class buildcompiler.reporting.report.DependencyChainStep(source: 'str', relationship: 'str', target: 'str', metadata: 'dict[str, Any]' = <factory>)[source]

Bases: object

Parameters:

  • source (str)

  • relationship (str)

  • target (str)

  • metadata (dict[str, Any])

source: str
relationship: str
target: str
metadata: dict[str, Any]
class buildcompiler.reporting.report.BuildReport(status: 'BuildStatus', executive_summary: 'str', stage_sections: 'list[StageReportSection]', selected_routes: 'list[RouteReport]', rejected_alternatives: 'list[RouteReport]', missing_inputs: 'list[dict[str, Any]]', required_approvals: 'list[dict[str, Any]]', warnings: 'list[dict[str, Any]]', next_actions: 'list[RecommendedAction]', dependency_chain: 'list[DependencyChainStep]', graph_summary: 'dict[str, Any]')[source]

Bases: object

Parameters:
status: BuildStatus
executive_summary: str
stage_sections: list[StageReportSection]
selected_routes: list[RouteReport]
rejected_alternatives: list[RouteReport]
missing_inputs: list[dict[str, Any]]
required_approvals: list[dict[str, Any]]
warnings: list[dict[str, Any]]
next_actions: list[RecommendedAction]
dependency_chain: list[DependencyChainStep]
graph_summary: dict[str, Any]
to_dict()[source]
Return type:

dict[str, Any]

to_json()[source]
Return type:

str

to_markdown()[source]
Return type:

str

buildcompiler.reporting.report.build_report(result, graph=None)[source]
Parameters:
Return type:

BuildReport

buildcompiler.reporting.summary

class buildcompiler.reporting.summary.BuildSummary(status: 'BuildStatus', final_product_count: 'int', missing_input_count: 'int', required_approval_count: 'int', warning_count: 'int')[source]

Bases: object

Parameters:

  • status (BuildStatus)

  • final_product_count (int)

  • missing_input_count (int)

  • required_approval_count (int)

  • warning_count (int)

status: BuildStatus
final_product_count: int
missing_input_count: int
required_approval_count: int
warning_count: int
to_dict()[source]
Return type:

dict[str, Any]

to_json()[source]
Return type:

str

to_markdown()[source]
Return type:

str

buildcompiler.reporting.summary.build_summary(result)[source]
Parameters:

result (FullBuildResult)

Return type:

BuildSummary

Legacy modules

buildcompiler.abstract_translator

class buildcompiler.abstract_translator.Plasmid(definition, strain_definition, doc)[source]

Bases: object

Parameters:

  • definition (ComponentDefinition)

  • strain_definition (ModuleDefinition)

  • doc (<module 'sbol2.document' from '/home/docs/checkouts/readthedocs.org/user_builds/buildcompiler/envs/latest/lib/python3.11/site-packages/sbol2/document.py'>)

buildcompiler.abstract_translator.extract_fusion_sites(plasmid, doc)[source]

Returns all fusion site component definitions from a plasmid.

Parameters:

  • plasmid (ComponentDefinition) – sbol2.ComponentDefinition representing the plasmid.

  • doc (Document) – sbol2.Document containing component definitions.

Returns:

A list of fusion site component definitions.

Return type:

List[ComponentDefinition]

buildcompiler.abstract_translator.extract_design_parts(design, doc)[source]

Returns definitions of parts in a design in sequential order.

Parameters:

  • design (ComponentDefinition) – sbol2.ComponentDefinition to extract parts from.

  • doc (Document) – sbol2.Document containing all component definitions.

Returns:

A list of component definitions in sequential order.

Return type:

List[ComponentDefinition]

buildcompiler.abstract_translator.copy_sequences(component_definition, target_doc, collection_doc)[source]

Copy all sequences referenced by a ComponentDefinition into target_doc.

buildcompiler.abstract_translator.get_or_pull(doc, sbh, uri, server_mode=False)[source]

Get an SBOL object from a Document. If missing, pull it from SynBioHub and retry.

Parameters:

  • doc (Document)

  • sbh (PartShop)

  • uri (str)

  • server_mode (bool)

buildcompiler.abstract_translator.extract_combinatorial_design_parts(design, doc, plasmid_doc)[source]

Extracts and returns a mapping of component definitions from a combinatorial design, in order. Variants of combinatinatorial components are entered in a list corresponding to the URI of the component in the abstract design.

Parameters:

  • design (ComponentDefinition) – The sbol2.ComponentDefinition representing the top-level design from which to extract parts.

  • doc (Document) – The primary sbol2.Document containing the base component definitions and combinatorial derivations.

  • plasmid_doc – An additional sbol2.Document used to resolve component variants (plasmid-specific variants referenced by combinatorial derivations).

Returns:

A dictionary mapping component identities to lists of variable component definitions.

  • Sequential design components map to lists containing a single definition.

  • Combinatorial variable components map to lists of variant definitions.

Return type:

Dict[str, List[sbol2.ComponentDefinition]]

buildcompiler.abstract_translator.extract_toplevel_definition(doc)[source]
Parameters:

doc (Document)

Return type:

ComponentDefinition

buildcompiler.abstract_translator.enumerate_design_variants(component_dict)[source]

Given a dict mapping variable component identities to lists of ComponentDefinitions, generate all possible design combinations as lists of ComponentDefinitions (in consistent order of keys).

buildcompiler.abstract_translator.construct_plasmid_dict(part_list, plasmid_collection)[source]

Builds a mapping from part display IDs to lists of compatible Plasmid objects.

For each part in the given list, this function searches the provided plasmid collection for plasmids that contain the part as a component. Each matching plasmid is wrapped in a Plasmid object and added to the dictionary under the part’s display ID.

Parameters:

  • part_list (List[ComponentDefinition]) – List of sbol2.ComponentDefinition objects representing the parts to match.

  • plasmid_collection (Document) – The sbol2.Document containing plasmids to search through.

Returns:

A dictionary mapping each part display ID to a list of corresponding Plasmid objects found in the collection.

Return type:

Dict[str, List[Plasmid]]

buildcompiler.abstract_translator.get_compatible_plasmids(plasmid_dict, backbone)[source]

Returns a list of Plasmid objects that can form a compatible assembly with the given backbone plasmid. The function selects one plasmid from each entry in the dictionary, ensuring that adjacent plasmids have matching MoClo fusion sites, and that the first and last plasmids are compatible with the backbone.

Parameters:

  • plasmid_dict (Dict[str, List[Plasmid]]) – A dictionary mapping assembly positions or categories to lists of Plasmid objects.

  • backbone (Plasmid) – The backbone Plasmid whose fusion sites define compatibility.

Returns:

A list of compatible Plasmid objects forming a sequential assembly.

Return type:

List[Plasmid]

buildcompiler.abstract_translator.translate_abstract_to_plasmids(abstract_design_doc, plasmid_collection, backbone_doc)[source]

Translates an abstract SBOLCanvas design into a set of compatible MoClo plasmid assemblies.

Takes an abstract design, identifies the appropriate component definitions and combinatorial derivations, and produces all possible plasmid combinations that can be assembled using the provided backbone and plasmid collection.

Parameters:

  • abstract_design_doc (Document) – The sbol2.Document representing the abstract genetic design. May include either a single component definition (generic design) or one or more combinatorial derivations (combinatorial design).

  • plasmid_collection (Document) – The sbol2.Document containing the available MoClo plasmid components used for matching and assembly.

  • backbone_doc (Document) – The sbol2.Document defining the backbone plasmid into which parts are assembled.

Returns:

  • For combinatorial designs: a list of unique compatible plasmids (Plasmid objects) representing all enumerated design variants.

  • For generic designs: a list of compatible plasmids for the single design instance.

Return type:

List[Plasmid]

buildcompiler.buildcompiler

class buildcompiler.buildcompiler.BuildCompiler(collections, sbh_registry, auth_token, sbol_doc=None, server_mode=False)[source]

Bases: object

Orchestrates the full build workflow for an SBOL design.

This class owns the build state (indexed plasmids/backbones) and provides a high-level API to execute the full workflow: collection indexing, domestication, lvl1 and lvl2 assembly, transformation, and plating.

Variables:

  • design – SBOL design (ComponentDefinition, ModuleDefinition, or CombinatorialDerivation).

  • plasmids – Indexed plasmids linked to strains/collections.

Parameters:

  • collections (List[str])

  • sbh_registry (str)

  • auth_token (str)

  • sbol_doc (Document)

  • server_mode (bool)

classmethod from_local_documents(collection_docs, design_doc=None)[source]

Create a BuildCompiler instance from already-loaded local SBOL documents.

Parameters:

  • collection_docs (list[Document])

  • design_doc (Document | None)

index_document(collection_doc)[source]
Parameters:

collection_doc (Document)

domestication(parts)[source]

Domesticate a list of genetic parts for Golden Gate assembly using the MoClo standard.

For each part, this method identifies the necessary domestication steps (e.g., removing internal BsaI sites) and generates the appropiate dsDNA for DNA synthesis and the corresponding domesticated plasmids as new ComponentDefinitions in the SBOL document.

Returns:

List of domesticated ComponentDefinitions ready for assembly.

Return type:

list[sbol2.ComponentDefinition]

Parameters:

parts (list[ComponentDefinition])

assembly_lvl1(abstract_designs, final_doc=<sbol2.document.Document object>, product_name='composite', backbone=None)[source]

Assemble level-1 plasmids for each gene/transcriptional unit.

Uses indexed plasmids/backbones and the current design to assemble lvl1 plasmids in the correct order.

Returns:

List of assembled lvl1 plasmids.

Return type:

list[Plasmid]

Raises:

LookupError – If compatible plasmids or backbones cannot be found.

Parameters:

  • abstract_designs (List[ComponentDefinition] | CombinatorialDerivation)

  • final_doc (Document)

  • product_name (str)

  • backbone (Plasmid | Dict[str, Plasmid] | None)

assembly_lvl2(abstract_design_doc, backbone=None, product_name=None)[source]

Assemble level-2 plasmids for the full design.

Uses the assembled lvl1 plasmids and the current design to assemble lvl2 plasmids in the correct order.

Returns:

List of assembled lvl2 plasmids.

Return type:

list[Plasmid]

Raises:

LookupError – If compatible plasmids or backbones cannot be found.

Parameters:

  • abstract_design_doc (Document)

  • backbone (Plasmid)

  • product_name (str)

transformation(assembly_products, chassis_name='E_coli_DH5alpha', transformation_doc=None)[source]

Generate deterministic transformation artifacts from assembly outputs.

The method accepts either: - Plasmid objects, - sbol2.ComponentDefinition plasmids, or - dictionaries containing at least a plasmid key with one of the above.

Parameters:

  • assembly_products (list) – Structured inputs produced by an assembly stage.

  • chassis_name (str) – Display id used for the chassis module and implementation.

  • transformation_doc (sbol2.Document | None) – Optional SBOL document to write outputs into.

Returns:

Structured transformation outputs including SBOL references, robot JSON intermediate, protocol placeholders, and logs.

Return type:

dict

Raises:

ValueError – If no valid plasmid inputs can be extracted.

plating(transformation_results, results_dir, protocol_type='manual', advanced_params=None, plate_name=None, plating_doc=None, overwrite=False)[source]

Generate plating layout artifacts and protocol metadata.

This implementation is file/metadata oriented and does not create new SBOL objects for plating.

Parameters:

  • transformation_results (dict)

  • results_dir (str | Path)

  • protocol_type (str)

  • advanced_params (dict | None)

  • plate_name (str | None)

  • plating_doc (Document | None)

  • overwrite (bool)

Return type:

Dict[str, Any]

full_build(designs=None, results_dir='full_build_results', overwrite=False, chassis_name='E_coli_DH5alpha', plating_protocol_type='manual', plating_advanced_params=None, product_name='full_build')[source]

Run the legacy full build workflow and return packaged artifacts.

The workflow is deliberately file-oriented: each stage writes explicit intermediates/protocol inputs under results_dir and the return value includes a zip archive containing those artifacts.

Parameters:

  • designs (Any)

  • results_dir (str | Path)

  • overwrite (bool)

  • chassis_name (str)

  • plating_protocol_type (str)

  • plating_advanced_params (dict | None)

  • product_name (str)

Return type:

Dict[str, Any]

extract_combinatorial_design_parts(design, derivation)[source]

Extracts and returns a mapping of component definitions from a combinatorial design, in order. Variants of combinatinatorial components are entered in a list corresponding to the URI of the component in the abstract design.

Parameters:

  • design (ComponentDefinition) – The top-level sbol2.ComponentDefinition representing the abstract design template whose components should be extracted in sequential order.

  • derivation (CombinatorialDerivation) – The sbol2.CombinatorialDerivation associated with design that defines variable components and their allowed variants.

Returns:

A dictionary mapping component identities to lists of variable component definitions.

  • Sequential design components map to lists containing a single definition.

  • Combinatorial variable components map to lists of variant definitions.

Return type:

Dict[str, List[sbol2.ComponentDefinition]]

buildcompiler.constants

buildcompiler.plasmid

class buildcompiler.plasmid.Plasmid(definition, strain_definition, plasmid_implementations, strain_implementations, doc)[source]

Bases: object

Parameters:

  • definition (ComponentDefinition)

  • strain_definition (ModuleDefinition)

  • plasmid_implementations (List[Implementation])

  • strain_implementations (List[Implementation])

  • doc (<module 'sbol2.document' from '/home/docs/checkouts/readthedocs.org/user_builds/buildcompiler/envs/latest/lib/python3.11/site-packages/sbol2/document.py'>)

buildcompiler.robotutils

buildcompiler.robotutils.load_json_or_dict(value)[source]

Load a JSON file path/string into a dict, or return dict-like input as-is.

buildcompiler.robotutils.normalize_plating_input(transformation_results, doc=None)[source]

Normalize transformation/plating inputs to a deterministic list of entries.

buildcompiler.robotutils.generate_96_well_positions(limit=96)[source]
buildcompiler.robotutils.write_plate_map_json(path, data)[source]
buildcompiler.robotutils.write_plate_map_csv(path, rows)[source]
Parameters:

rows (List[Dict[str, Any]])

buildcompiler.robotutils.write_manual_plating_protocol(path, plate_id, plate_rows, advanced_params)[source]
buildcompiler.robotutils.write_plating_protocol_script(path, plating_data, advanced_params)[source]
buildcompiler.robotutils.run_opentrons_script_to_zip(opentrons_script_path, plating_json_path, zip_name=None, overwrite=False)[source]
buildcompiler.robotutils.assembly_plan_RDF_to_JSON(file, output_path=None)[source]
Parameters:

output_path (str | Path | None)

buildcompiler.robotutils.run_opentrons_script_with_json_to_zip(opentrons_script_path, json_file_path, zip_name=None, overwrite=False)[source]

Runs opentrons_simulate on an Opentrons script + JSON, captures stdout/stderr, and writes a ZIP file next to the original opentrons script.

Returns: Path to the created zip file.

Parameters:

  • opentrons_script_path (str)

  • json_file_path (str)

  • zip_name (str | None)

  • overwrite (bool)

Return type:

Path

buildcompiler.sbol2build

class buildcompiler.sbol2build.Assembly(part_plasmids, backbone_plasmid, restriction_enzyme, ligase, source_document, final_document, composite_prefix='composite')[source]

Bases: object

Creates an Assembly Plan.

Parameters:

  • part_plasmids (List[Plasmid]) – List of part-in-backbone plasmids to be assembled.

  • backbone_plasmid (Plasmid) – Acceptor backbone into which parts are inserted.

  • restriction_enzyme (Implementation) – SBOL Implementation representing the restriction enzyme (e.g. BsaI) used to digest parts during assembly.

  • ligase (Implementation) – SBOL Implementation representing the ligase (e.g. T4) used to ligate digested parts.

  • source_document (Document) – SBOL Document containing the source part/plasmid definitions.

  • final_document (Document) – SBOL Document where assembled composite plasmid definitions will be written.

  • composite_prefix (str) – Prefix used when naming composite plasmid definitions. Defaults to ‘composite’.

run(include_extracted_parts=False)[source]

Run the full Golden Gate assembly simulation.

Executes the following steps in order:

  1. Calls part_digestion() on each plasmid in part_plasmids using restriction_enzyme, appending extracted parts to source_document.

  2. Calls backbone_digestion() on the first implementation of backbone, appending the linearised backbone to source_document.

  3. Calls ligation() on all extracted parts and the backbone to produce composite plasmid implementations, written to final_document.

  4. Wraps each composite implementation in a Plasmid object and returns the full list alongside the populated final_document.

Parameters:

include_extracted_parts (bool) – If True, extracted part and backbone definitions are also written to final_document in addition to source_document. Defaults to False.

Returns:

A tuple of (composite plasmids, final document), where composite plasmids is a list of Plasmid objects built from the ligated implementations, and final document is the populated sbol2.Document containing all assembly outputs.

Return type:

Tuple[List[Plasmid], Document]

initialize_assembly_activity()[source]
class buildcompiler.sbol2build.Transformation(plasmids, chassis_name, source_document)[source]

Bases: object

Create SBOL transformation records from plasmid/chassis inputs.

Mirrors the orchestration pattern used by Assembly, but for chemical transformation into a chassis strain.

Parameters:

  • plasmids (List[Plasmid])

  • chassis_name (str)

  • source_document (Document)

chemical_transformation()[source]
Return type:

list[dict]

buildcompiler.sbol2build.rebase_restriction_enzyme(name, **kwargs)[source]

Creates an ComponentDefinition Restriction Enzyme Component from rebase.

Parameters:

  • name (str) – Name of the SBOL ExternallyDefined, used by PyDNA. Case sensitive, follow standard restriction enzyme nomenclature, i.e. ‘BsaI’

  • kwargs – Keyword arguments of any other ComponentDefinition attribute.

Returns:

A ComponentDefinition object.

Return type:

ComponentDefinition

buildcompiler.sbol2build.dna_componentdefinition_with_sequence(identity, sequence, molecule=False, **kwargs)[source]

Creates a DNA ComponentDefinition and its Sequence.

Parameters:

  • identity (str) – The identity of the Component. The identity of Sequence is also identity with the suffix ‘_seq’.

  • sequence (str) – The DNA sequence of the Component encoded in IUPAC.

  • molecule (bool) – Boolean value: true if type should be DNA molecule, false if DNA region

  • kwargs – Keyword arguments of any other Component attribute.

Returns:

A tuple of ComponentDefinition and Sequence.

Return type:

Tuple[ComponentDefinition, Sequence]

buildcompiler.sbol2build.part_in_backbone_from_sbol(identity, sbol_comp, part_location, part_roles, fusion_site_length, document, linear=False, **kwargs)[source]

Restructures a plasmid ComponentDefinition to follow the part-in-backbone pattern with scars following BP011. It overwrites the SBOL2 ComponentDefinition provided. A part inserted into a backbone is represented by a Component that includes both the part insert as a feature that is a SubComponent and the backbone as another SubComponent. For more information about BP011 visit https://github.com/SynBioDex/SBOL-examples/tree/main/SBOL/best-practices/BP011

Parameters:

  • identity (str | None) – The identity of the Component, is its a String it build a new SBOL Component, if None it adds on top of the input. The identity of Sequence is also identity with the suffix ‘_seq’.

  • sbol_comp (ComponentDefinition) – The SBOL2 Component that will be used to create the part in backbone Component and Sequence.

  • part_location (List[int]) – List of 2 integers that indicates the start and the end of the unitary part. Note that the index of the first location is 1, as is typical practice in biology, rather than 0, as is typical practice in computer science.

  • part_roles (List[str]) – List of strings that indicates the roles to add on the part.

  • fusion_site_length (int) – Integer of the length of the fusion sites (eg. BsaI fusion site lenght is 4, SapI fusion site lenght is 3)

  • linear (bool) – Boolean than indicates if the backbone is linear, defaults to False (cicular topology).

  • kwargs – Keyword arguments of any other Component attribute.

  • document (Document)

Returns:

ModuleDefinition in the form that sbolcanvas would output

Return type:

Tuple[ComponentDefinition, Sequence]

buildcompiler.sbol2build.is_circular(obj)[source]

Check if an SBOL Component or Feature is circular.

Parameters:

obj (ComponentDefinition) – design to be checked

Returns:

true if circular

Return type:

bool

buildcompiler.sbol2build.part_digestion(reactant, restriction_enzymes, assembly_activity, document)[source]

Simulate restriction digestion of a part plasmid and extract the insert.

Uses PyDNA to cut the reactant sequence, then constructs SBOL representations of the extracted part, its 5’ and 3’ overhangs, and any derived scar sequences. Each enzyme and the reactant implementation are recorded as usages on assembly_activity.

Expects the reactant to be circular with 2 digest products, or linear with 3 (backbone | part | backbone). The shorter circular product or middle linear product is taken as the extracted insert.

Parameters:

  • reactant (Plasmid) – Part-in-backbone plasmid to digest.

  • restriction_enzymes (List[Implementation]) – Restriction enzyme implementations; the corresponding ComponentDefinition.name must match a PyDNA/ReBase enzyme name (e.g. 'BsaI').

  • assembly_activity (Activity) – SBOL Activity to record reactant and enzyme usages on.

  • document (Document) – Source SBOL document used to resolve referenced definitions and sequences.

Returns:

A tuple of (extracts, activity), where extracts is a list of (ComponentDefinition, Sequence) pairs covering the extracted part, overhangs, and scar definitions, and activity is the updated assembly_activity.

Raises:

  • TypeError – If the reactant has no recognised DNA type.

  • ValueError – If the reactant does not have exactly one sequence, or if the number of digest products is unsupported for the reactant topology.

Return type:

Tuple[List[Tuple[ComponentDefinition, Sequence]], Activity]

buildcompiler.sbol2build.backbone_digestion(reactant, restriction_enzymes, assembly_activity, document)[source]

Simulate restriction digestion of a backbone plasmid and extract the linearised vector.

Mirrors part_digestion() but targets the backbone: for a circular reactant with 2 digest products the longer fragment is taken as the open backbone; for a linear reactant with 3 products the outer prefix/suffix fragments are used. The resulting open-backbone ComponentDefinition, its 5’ and 3’ overhangs, and any matched scar sequences are returned as SBOL objects. The reactant implementation and each enzyme are recorded as usages on assembly_activity.

Parameters:

  • reactant (Plasmid) – SBOL Implementation whose built URI resolves to the backbone ComponentDefinition in document.

  • restriction_enzymes (List[Implementation]) – Restriction enzyme implementations; the corresponding ComponentDefinition.name must match a PyDNA/ReBase enzyme name (e.g. 'BsaI').

  • assembly_activity (Activity) – SBOL Activity to record reactant and enzyme usages on.

  • document (Document) – Source SBOL document used to resolve referenced definitions and sequences.

Returns:

A tuple of (extracts, activity), where extracts is a list of (ComponentDefinition, Sequence) pairs covering the open backbone, overhangs, and scar definitions, and activity is the updated assembly_activity.

Raises:

  • TypeError – If the reactant has no recognised DNA type.

  • ValueError – If the reactant does not have exactly one sequence, or if the number of digest products is unsupported for the reactant topology.

Return type:

Tuple[List[Tuple[ComponentDefinition, Sequence]], Activity]

buildcompiler.sbol2build.number_to_suffix(n)[source]

Helper function for generating scar suffixes of the form: \(S=(A,B,C,…,Z,AA,AB,AC,…,AZ,BA,BB,…, S_n)\)

Parameters:

n – Number to convert to character suffix

Returns:

Character suffix corresponding to n

buildcompiler.sbol2build.ligation(reactants, assembly_activity, composite_prefix, source_document, final_document, ligase)[source]

Ligates Components using base complementarity and creates product Components and a ligation Interaction.

Parameters:

  • reactants (List[ComponentDefinition]) – Extracted part and backbone ComponentDefinition objects to ligate.

  • assembly_activity (Activity) – SBOL activity to track assembly inputs & outputs

  • composite_prefix (str) – Prefix used when naming composite ComponentDefinition and Implementation identities.

  • source_document (Document) – SBOL Document containing all reactant definitions.

  • final_document (Document) – SBOL Document that receives composite definitions and implementations.

  • ligase (Implementation) – SBOL Implementation of the ligase (e.g. T4).

Returns:

List of sbol2.Implementation objects, one per composite plasmid generated.

Return type:

List[Implementation]

buildcompiler.sbol2build.append_extracts_to_doc(extract_tuples, doc)[source]

Helper function for batch adding sbol2.ComponentDefinition and sbol2.Sequence to an sbol2.Document

Parameters:

  • extract_tuples (List[Tuple[ComponentDefinition, Sequence]]) – list of tuples of sbol2.ComponentDefinition and sbol2.Sequence

  • doc (Document) – document which the content is to be added to

Return type:

None

buildcompiler.sbol2build.add_object_to_doc(obj, doc)[source]
Parameters:

  • obj (SBOLObject)

  • doc (Document)

Return type:

None

buildcompiler.transformation

buildcompiler.transformation.bacterial_transformation(plasmids, chassis_impl, chassis_md, transformation_doc)[source]
Parameters:

  • plasmids (List[Plasmid])

  • chassis_impl (Implementation)

  • chassis_md (ModuleDefinition)

  • transformation_doc (Document)