> ## 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. # Beam Search Optimizer > Beam search over an autoregressive language model: extends a single segment in fixed-length steps, scoring each candidate's full sequence against the constraints and keeping the top-scoring beams at every step.
step 1step 2step 3step 4prompteach step: extend +beam\_length tokens → score full sequence → keep top-Kkeptprunedbest path
step 1step 2step 3step 4prompteach step: extend +beam\_length tokens → score full sequence → keep top-Kkeptprunedbest path

This optimizer is open source. Any third-party models, product names, or trademarks referenced are the property of their respective owners, and Proto is not affiliated with them.

Source
evo-design/proto-language/proto\_language/optimizer/beam\_search\_optimizer.py
View source
Optimizer contributors
Beam search optimizer for sequence generation. This optimizer implements beam search for sequence optimization where a single target segment is generated with beam search. The optimizer maintains K beams (running sequences) and generates K x N total proposals at each step by producing N variations per beam. After constraint evaluation on the FULL accumulated sequence, only the top K sequences by energy are retained for the next step. The segment is split into ceil(sequence\_length / beam\_length) steps. Each step asks the single autoregressive generator for beam\_length new tokens per proposal (the last step is truncated to the remaining tokens), scores each proposal on its full accumulated sequence, and resamples any beam left with fewer than proposals\_per\_result valid proposals (up to max\_resample\_attempts, raising RuntimeError if a beam still falls short) before ranking. Within a beam, proposals are kept by their most recent step energy; across beams, the top num\_results survivors are ranked by score\_by ("mean" averages a beam's per-step energies, "last" uses only the most recent), become the next step's parent beams, and seed the final result\_sequences. prepend\_prompt controls whether the prompt is included in the output, and use\_kv\_caching reuses generator cache state across steps (requires a KV-cache-capable generator). Use it for long autoregressive design under sequence-level constraints; it targets a single segment and requires a protein/DNA language-model generator (Evo1/Evo2/ProGen2), not a CPU generator. ## How It Works Beam search extends a single segment step by step, pruning weak beams as it grows. Beam search grows one segment left to right. The segment is split into `num_beams = ⌈ L / beam_length ⌉` steps; at each step every one of the `K = num_results` beams is extended by `beam_length` tokens in `proposals_per_result` variations, each candidate is scored on its **full accumulated sequence**, and only the top `K` beams survive: ``` num_beams = ⌈ L / beam_length ⌉ score_agg(beam) = mean(beam_scores) if score_by = "mean" = beam_scores[-1] if score_by = "last" keep the K beams with smallest score_agg ``` Beams left with too few valid proposals are resampled (up to `max_resample_attempts`). Beam search starts from `prompt` and ignores upstream results; `use_kv_caching` reuses the generator's KV cache across steps. ## API Reference
ConfigBeamSearchOptimizerConfig Source
Configuration object for BeamSearchOptimizer. This class defines configuration parameters for the beam search optimizer, which generates a single long segment by splitting it into beams of `beam_length` tokens and performing beam search at each beam boundary. Non-empty seed sequence that every beam begins from and extends (e.g. 'ATCG' for DNA). Number of beams (top-K by energy) retained at each beam boundary. Overrides program-level count. Number of proposals to generate per result sequence at each beam step. Tokens per beam-search step before re-ranking; segment split into ceil(len/this) steps. 'mean' averages a beam's per-step energies across all steps; 'last' uses only the most recent. Options: `mean`, `last` Whether to prepend the prompt to the generated sequence in the output. Reuse cached KV state across beam steps to speed up generation; needs a KV-capable generator. Maximum number of times to resample beams with invalid (inf/NaN) energies before giving up. Random seed for reproducible optimization, generator, and constraint tool streams. Save history and log progress every N steps. Step 0 and final step always saved. Save granular per-proposal results (accept/reject) in history snapshots. Emit per-step debug information about proposals, scores, and acceptance through the logger.
## Usage ```python python icon="python" theme={null} >>> from proto_language.constraint import gc_content_constraint >>> from proto_language.core import Constraint, Construct, Segment >>> from proto_language.generator import Evo2Generator, Evo2GeneratorConfig >>> >>> segment = Segment(length=10000, sequence_type="dna") >>> generator = Evo2Generator(Evo2GeneratorConfig(prompts="ATCG")) >>> gc = Constraint( ... inputs=[segment], function=gc_content_constraint, function_config={"min_gc": 40, "max_gc": 60} ... ) >>> beam_search = BeamSearchOptimizer( ... target_segment=segment, ... constructs=[Construct([segment])], ... generators=[generator], ... constraints=[gc], ... config=BeamSearchOptimizerConfig( ... prompt="ATCG", beam_length=2000, num_results=5, proposals_per_result=10 ... ), ... ) >>> # beam_search.run() drives the loop ``` ## Metadata | Property | Value | | ---------------------- | ------------------------- | | Key | `beam-search` | | Class | `BeamSearchOptimizer` | | Targets Single Segment | `True` | | Uses GPU | `False` | | Compatible Generators | `evo1`, `evo2`, `progen2` |