> ## 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.
# Architecture Overview
> How Proto turns biological requirements into optimized sequences
Proto translates a set of biological requirements into optimized sequences. The requirements are declared as constraints, and the framework searches sequence space for sequences that satisfy them.
Without a framework, sequence design is a manual loop: a sequence is designed by hand, prediction tools are run one at a time, the results are evaluated, and the sequence is revised over many iterations. Proto automates this loop. Requirements are expressed once as constraints, an optimizer searches sequence space, and the output is a set of sequences ranked by score.
***
## The Pipeline
Every design follows the same five-stage pipeline:
***
## Core Components
The fundamental data unit: a biological string (DNA, RNA, protein, or ligand) with type validation and rich metadata.
A region to design. Maintains dual pools of proposal and result sequences during optimization.
An ordered collection of Segments representing a complete biological design, like a gene expression cassette.
Proposes new sequences through mutation, autoregressive generation, inverse folding, or gradient-based design.
Scores how well sequences meet requirements. Returns 0.0 (perfect) to 1.0 (worst violation).
Orchestrates the generate-evaluate-select loop using search strategies such as MCMC or beam search.
A **Program** chains multiple Optimizers together for multi-stage pipelines (e.g., coarse exploration followed by fine-tuning). See [Programs](/docs/language/concepts/programs).
***
## Data Flow
**Segments** specify the regions to be designed, for example a 100 bp promoter, a 300-residue enzyme, or an existing sequence to optimize. They are combined into a **Construct** representing the full biological unit.
```python python icon="python" theme={null}
promoter = Segment(length=100, sequence_type="dna", label="promoter")
cds = Segment(length=900, sequence_type="dna", label="cds")
construct = Construct([promoter, cds])
```
Each **Generator** is assigned to a Segment and proposes candidate sequences. Different generators use different strategies: random mutation, model-guided generation, or inverse folding.
```python python icon="python" theme={null}
generator = RandomNucleotideGenerator(RandomNucleotideGeneratorConfig())
generator.assign(promoter)
```
**Constraints** evaluate sequences and return a score from 0.0 (perfect) to 1.0 (worst). They can operate on individual segments or across multiple segments.
```python python icon="python" theme={null}
gc_constraint = Constraint(
inputs=[promoter],
function=gc_content_constraint,
function_config={"min_gc": 45, "max_gc": 55}
)
```
The **Optimizer** drives the search loop: generate proposals, score them with constraints, select the best. It repeats until a stopping criterion is reached.
```python python icon="python" theme={null}
optimizer = MCMCOptimizer(
constructs=[construct],
generators=[generator],
constraints=[gc_constraint],
config=MCMCOptimizerConfig(num_steps=1000)
)
```
After optimization, the best sequences live in each Segment's `result_sequences` pool. The Construct's `joined_sequences` gives the full concatenated results.
```python python icon="python" theme={null}
program = Program(optimizers=[optimizer], num_results=1)
program.run()
for seq in construct.joined_sequences:
print(seq.sequence)
print(seq.metadata["segments"]) # Per-segment constraint scores
```
***
## The Dual Pool Architecture
A key design decision in Proto is that each Segment maintains **two separate sequence pools**. This separation lets optimizers explore freely without losing the best solutions found so far.
### Proposal Pool
* **Purpose**: Workspace for the optimizer
* **Populated by**: Generators (mutations, new proposals)
* **Consumed by**: Constraints (scoring) and Optimizer (selection)
* **Lifecycle**: Rebuilt every optimization step
### Result Pool
* **Purpose**: Best results found so far
* **Populated by**: Optimizer (after ranking proposals)
* **Consumed by**: User (final output), next stage in a Program
* **Lifecycle**: Persists across optimization steps and stages
***
## Design Patterns
The simplest pattern: one segment, one constraint, one optimizer, used for a single design objective.
**Example**: Design a 100 bp DNA promoter with 50-60% GC content.
```python python icon="python" theme={null}
from proto_language.core import Segment, Construct
from proto_language import Program, Constraint
from proto_language.generator import RandomNucleotideGenerator, RandomNucleotideGeneratorConfig
from proto_language.constraint import gc_content_constraint
from proto_language.optimizer import MCMCOptimizer, MCMCOptimizerConfig
segment = Segment(length=100, sequence_type="dna", label="promoter")
construct = Construct([segment])
generator = RandomNucleotideGenerator(RandomNucleotideGeneratorConfig())
generator.assign(segment)
constraint = Constraint(
inputs=[segment],
function=gc_content_constraint,
function_config={"min_gc": 50, "max_gc": 60}
)
optimizer = MCMCOptimizer(
constructs=[construct],
generators=[generator],
constraints=[constraint],
config=MCMCOptimizerConfig(num_steps=1000)
)
program = Program(optimizers=[optimizer], num_results=1)
program.run()
```
Multiple constraints on the same segment. Scores are combined into a weighted energy value that the optimizer minimizes.
**Example**: Design a protein with high stability (pLDDT) and minimal low-complexity regions.
```python python icon="python" theme={null}
segment = Segment(length=200, sequence_type="protein", label="enzyme")
construct = Construct([segment])
generator = ESM2Generator(ESM2GeneratorConfig())
generator.assign(segment)
constraints = [
Constraint(
inputs=[segment],
function=structure_plddt_constraint,
function_config={"structure_tool": "esmfold"},
weight=2.0, # Higher weight = more important
),
Constraint(
inputs=[segment],
function=protein_complexity_constraint,
function_config={"max_low_complexity": 0.3},
weight=1.0,
),
]
optimizer = MCMCOptimizer(
constructs=[construct],
generators=[generator],
constraints=constraints,
config=MCMCOptimizerConfig(num_steps=500)
)
```
Optimizers are chained for coarse-to-fine search. The first stage explores broadly with cheap constraints; later stages refine with expensive ones. Stages share the same Construct objects, so results flow through.
**Example**: Broad exploration with sequence-level constraints, then structure-guided refinement.
```python python icon="python" theme={null}
segment = Segment(length=300, sequence_type="protein", label="target")
construct = Construct([segment])
# Stage 1: Broad exploration with a fast sequence-quality constraint
random_generator = RandomProteinGenerator(RandomProteinGeneratorConfig())
random_generator.assign(segment)
complexity = Constraint(
inputs=[segment],
function=protein_complexity_constraint,
function_config={"max_low_complexity": 0.3},
)
stage1 = RejectionSamplingOptimizer(
constructs=[construct],
generators=[random_generator],
constraints=[complexity],
config=RejectionSamplingOptimizerConfig(num_samples=5000, num_results=50),
)
# Stage 2: Refinement with expensive structure prediction (same construct object)
esm2_generator = ESM2Generator(ESM2GeneratorConfig())
esm2_generator.assign(segment)
plddt = Constraint(
inputs=[segment],
function=structure_plddt_constraint,
function_config={"structure_tool": "esmfold"},
)
stage2 = MCMCOptimizer(
constructs=[construct],
generators=[esm2_generator],
constraints=[plddt],
config=MCMCOptimizerConfig(num_steps=200),
)
program = Program(optimizers=[stage1, stage2], num_results=10)
program.run() # Stage 1 results feed into Stage 2
```
Multi-stage pipelines must share the **same Construct objects by identity** (not copies). This is how results flow from one stage to the next.
Multiple regions are designed together. Constraints can operate on individual segments or across multiple segments for interaction-aware design.
**Example**: Design a promoter and coding sequence together, with cross-segment constraints.
```python python icon="python" theme={null}
promoter = Segment(length=100, sequence_type="dna", label="promoter")
cds = Segment(length=900, sequence_type="dna", label="cds")
construct = Construct([promoter, cds])
# Separate generators for each region
gen_promoter = RandomNucleotideGenerator(RandomNucleotideGeneratorConfig())
gen_promoter.assign(promoter)
gen_cds = RandomNucleotideGenerator(RandomNucleotideGeneratorConfig())
gen_cds.assign(cds)
constraints = [
# Per-segment constraints
Constraint(inputs=[promoter], function=gc_content_constraint,
function_config={"min_gc": 45, "max_gc": 55}),
Constraint(inputs=[cds], function=gc_content_constraint,
function_config={"min_gc": 40, "max_gc": 60}),
# Constraints can also span segments, e.g. inputs=[promoter, cds],
# for interaction-aware design across regions.
]
optimizer = MCMCOptimizer(
constructs=[construct],
generators=[gen_promoter, gen_cds],
constraints=constraints,
config=MCMCOptimizerConfig(num_steps=1000)
)
```
***
## Choosing a Pattern
***
## Next Steps
The fundamental data unit
Design regions and dual pools
Scoring functions for design objectives
A first design, end to end