> ## Documentation Index
> Fetch the complete documentation index at: https://proto.evodesign.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Constructs
> Combining segments into complete biological designs
# Constructs
A **Construct** is an ordered collection of [Segments](/docs/language/concepts/segments) representing a complete biological design. Just as a gene is assembled from regulatory and coding parts (a promoter, ribosome binding site, coding sequence, and terminator), a Construct assembles Segment objects into a coherent whole.
The Construct handles validation (all segments must share the same type), auto-labeling, and, crucially, **joined sequence concatenation**, which gives the full designed sequence after optimization.
***
## Creating Constructs
Pass an ordered list of Segments to create a Construct:
```python python icon="python" theme={null}
from proto_language.core import Segment, Construct
promoter = Segment(length=100, sequence_type="dna", label="promoter")
rbs = Segment(sequence="AGGAGG", sequence_type="dna", label="rbs")
cds = Segment(length=900, sequence_type="dna", label="cds")
terminator = Segment(length=50, sequence_type="dna", label="terminator")
gene_construct = Construct(
[promoter, rbs, cds, terminator],
label="gene_construct"
)
```
Segment order matters; it defines the physical arrangement of the final biological sequence.
***
## Validation Rules
Constructs enforce several rules at creation time to catch design errors early:
**All segments must share the same sequence type.** DNA and protein segments cannot be mixed in one Construct. To represent a gene and its protein product, use separate Constructs.
**All segments must share the same valid character set.** If one segment uses custom `valid_chars`, all segments in the Construct must use the same set.
**Segment labels must be unique** within a Construct. Duplicate labels cause a `ValueError`.
```python python icon="python" theme={null}
# Valid: all DNA segments
construct = Construct([
Segment(length=50, sequence_type="dna", label="upstream"),
Segment(length=100, sequence_type="dna", label="target"),
])
# Invalid: mixed types -> raises ValueError
construct = Construct([
Segment(length=50, sequence_type="dna", label="gene"),
Segment(length=100, sequence_type="protein", label="protein"), # Error!
])
# Invalid: duplicate labels -> raises ValueError
construct = Construct([
Segment(length=50, sequence_type="dna", label="region"),
Segment(length=100, sequence_type="dna", label="region"), # Error!
])
```
***
## Joined Sequences
The most important property of a Construct is `joined_sequences`. After optimization, this gives the full concatenated sequence from all segments, with merged metadata from each segment.
```python python icon="python" theme={null}
# After optimization, get the full sequences
for seq in construct.joined_sequences:
print(f"Full sequence ({len(seq)} bp): {seq.sequence[:50]}...")
print(f"Segments: {list(seq.metadata.get('segments', {}).keys())}")
```
### Multiple Results (Top-K)
When the optimizer selects multiple results per segment (e.g., top-3), `joined_sequences` pairs them by index:
```python python icon="python" theme={null}
# If each segment has 3 result sequences:
# segment_1.result_sequences = [Seq("AAA"), Seq("TTT"), Seq("GGG")]
# segment_2.result_sequences = [Seq("CCC"), Seq("AAA"), Seq("TTT")]
construct.joined_sequences
# [Sequence("AAACCC"), # index 0 from each segment
# Sequence("TTTAAA"), # index 1 from each segment
# Sequence("GGGTTT")] # index 2 from each segment
```
All segments in a Construct must have the **same number** of result sequences. `joined_sequences` raises a `RuntimeError` if the per-segment result pools have mismatched lengths.
***
## Auto-Labeling
Both Constructs and Segments support automatic labeling:
```python python icon="python" theme={null}
# Unlabeled segments get position-based labels
construct = Construct([
Segment(length=50, sequence_type="dna"), # -> "segment_0"
Segment(length=100, sequence_type="dna"), # -> "segment_1"
Segment(length=30, sequence_type="dna", label="my_term"), # -> "my_term"
])
construct.segments[0].label # "segment_0"
construct.segments[2].label # "my_term"
```
Always provide explicit labels for clarity. They appear in constraint metadata and make optimization results easier to interpret.
***
## Biological Design Patterns
The classic pattern for designing gene circuits: promoter, RBS, coding sequence, and terminator in series.
```python python icon="python" theme={null}
# Bacterial gene
promoter = Segment(length=100, sequence_type="dna", label="promoter")
rbs = Segment(sequence="AGGAGG", sequence_type="dna", label="rbs")
cds = Segment(length=900, sequence_type="dna", label="cds")
terminator = Segment(
sequence="AACAAAATCGCAATGATTTCGATTTTAAAAGGTCTG",
sequence_type="dna",
label="terminator"
)
gene_construct = Construct(
[promoter, rbs, cds, terminator],
label="gene_construct"
)
```
Use cross-segment constraints to evaluate predicted expression levels considering all elements together.
Design fusion proteins with fixed structural elements and variable functional domains.
```python python icon="python" theme={null}
# Antibody-like fusion protein
signal = Segment(
sequence="MKFLILLFNILCLFPVLAAD",
sequence_type="protein",
label="signal_peptide"
)
vh = Segment(length=120, sequence_type="protein", label="vh_domain")
linker = Segment(
sequence="GGGGSGGGGSGGGGS",
sequence_type="protein",
label="linker"
)
vl = Segment(length=110, sequence_type="protein", label="vl_domain")
scfv = Construct(
[signal, vh, linker, vl],
label="scfv_construct"
)
```
The linker and signal peptide are fixed; only the VH and VL domains are optimized.
Design guide RNA components with fixed scaffold and variable spacer.
```python python icon="python" theme={null}
# CRISPR-Cas9 guide RNA
spacer = Segment(length=20, sequence_type="rna", label="spacer")
scaffold = Segment(
sequence="GUUUUAGAGCUAGAAAUAGCAAGUUAAAAUAAGGCUAGUCCGUUAUCAACUUGAAAAAGUGGCACCGAGUCGGUGC",
sequence_type="rna",
label="scaffold"
)
guide_rna = Construct(
[spacer, scaffold],
label="sgrna"
)
```
Only the spacer is optimized; the scaffold stays constant. Constraints can score on-target specificity and off-target avoidance.
Design a multi-gene insert with regulatory elements.
```python python icon="python" theme={null}
# Two-gene operon
promoter = Segment(length=80, sequence_type="dna", label="promoter")
gene1 = Segment(length=600, sequence_type="dna", label="gene1")
intergenic = Segment(length=30, sequence_type="dna", label="intergenic")
gene2 = Segment(length=450, sequence_type="dna", label="gene2")
terminator = Segment(length=40, sequence_type="dna", label="terminator")
operon = Construct(
[promoter, gene1, intergenic, gene2, terminator],
label="operon_insert"
)
```
Cross-segment constraints can evaluate the entire operon for predicted expression balance between the two genes.
***
## Working with Optimizers
Optimizers take a list of Constructs to optimize. Multiple optimizers in a [Program](/docs/language/concepts/programs) must share the **same Construct objects by identity** so that results persist between stages.
```python python icon="python" theme={null}
# Correct: same construct object passed to both stages
construct = Construct([promoter, cds], label="my_design")
stage1 = RejectionSamplingOptimizer(
constructs=[construct], # same object
generators=[broad_gen],
constraints=[fast_constraint],
config=RejectionSamplingOptimizerConfig(num_samples=5000, num_results=50)
)
stage2 = MCMCOptimizer(
constructs=[construct], # same object: results flow through
generators=[fine_gen],
constraints=[expensive_constraint],
config=MCMCOptimizerConfig(num_steps=500)
)
program = Program(optimizers=[stage1, stage2], num_results=10)
program.run()
# Results are in the construct's segments
for seq in construct.joined_sequences:
print(seq.sequence)
```
Do **not** create separate Construct instances for each optimizer stage. The result sequences from stage 1 would be lost. Always reuse the same Construct object.
***
## Properties
| Property | Type | Description |
| ------------------ | --------------------- | ------------------------------------------- |
| `segments` | `tuple[Segment, ...]` | Ordered tuple of Segment objects |
| `sequence_type` | `SequenceType` | Shared type across all segments (read-only) |
| `valid_chars` | `Optional[Set[str]]` | Shared valid characters (read-only) |
| `joined_sequences` | `List[Sequence]` | Concatenated sequences from result pools |
| `label` | `Optional[str]` | Identifier for this construct |
***
## Serialization
Constructs serialize to dictionaries, including all their segments and both sequence pools:
```python python icon="python" title="Serialize" theme={null}
data = construct.to_dict()
# {
# "segments": [
# { "label": "promoter", "sequence_length": 100, ... },
# { "label": "cds", "sequence_length": 900, ... },
# ],
# "sequence_type": "dna",
# "valid_chars": ["A", "C", "G", "T"],
# "label": "gene_construct"
# }
```
```python python icon="python" title="Deserialize" theme={null}
restored = Construct.from_dict(data)
restored.label # "gene_construct"
len(restored.segments) # 2
restored.segments[0].label # "promoter"
```
***
## Next Steps
How generators propose candidate sequences for each segment
Scoring functions for design objectives
Chain optimizers into multi-stage pipelines
See how Constructs fit into the full architecture