Skip to content
Projects

kumarshreshtha/protuna has 57 GitHub stars and 2 forks. GitHot measured 0 stars in 24 hours and +1 in 7 days. Last checked 2026-11-18 01:26 UTC. Last push 2026-11-05.

How these counts are measured

What you can do

  • Guided generation: Steer protein language models towards your design objectives with reward-guided generation – Feynman–Kac steering, classifier guidance, and beam search.
  • Scalable screening: Ray-based distributed streaming APIs for large-scale screening on local accelerators or clusters.
  • Modular campaigns: Combine interchangeable samplers, predictors, constraints, and acquisition strategies.
  • Multiple design goals: Optimize for multiple properties with a primary objective and inequality constraints on the others.

Measured star growth

in 24h
0
in 7 days
+1
in 15 days
Collecting history
in 1 month
Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

Optimization framework for AI-guided protein engineering

Machine Learning

README.md

Original

Protuna Protuna

Tests Version Language Docs License

Protuna is an optimization framework for iterative protein engineering campaigns. Starting from historical mutagenesis data or a single hit[^1], it proposes the batch of variants to test next.

Features

  • Guided generation: Steer protein language models towards your design objectives with reward-guided generation – Feynman–Kac steering, classifier guidance, and beam search.
  • Scalable screening: Ray-based distributed streaming APIs for large-scale screening on local accelerators or clusters.
  • Modular campaigns: Combine interchangeable samplers, predictors, constraints, and acquisition strategies.
  • Multiple design goals: Optimize for multiple properties with a primary objective and inequality constraints on the others.

Getting Started

Installation

Protuna requires Python 3.12 or higher.

pip install protuna

Building with AI Agents

The protuna-skills plugin gives AI coding agents the guidance and examples needed to work with Protuna. Use it to build, and run optimization pipelines, configure distributed inference, or extend the framework with custom components.

See the plugin guide for installation instructions for coding and science agents.

Quickstart

The following code builds and runs a simple Pipeline.

It starts by defining which mutations are allowed and how to sample narrower search spaces. The pipeline then samples random protein sequences in those subspaces, uses a multiple sequence alignment (MSA) to score them based on amino acid frequencies at the mutated sites, and selects up to 20 of the highest-scoring sequences.

from protuna import data
from protuna import optim
from protuna.optim import acquisitions
from protuna.optim import predictors
from protuna.optim import rules
from protuna.optim import samplers
from protuna.optim import spaces

dataset = data.get_dataset("gb1", source=data.DatasetSource.FLIP)
tokens = data.tokenizer.encode(dataset.target_sequence)
msa = data.TokenizedMSA.from_file(
    dataset.get_msa_path(data.MSAProtocol.ColabFold), format="a3m"
)
design_space = spaces.DesignSpace.from_rules(
    rules=[
        # Positions are illustrative and use zero-based indexing.
        rules.AllowOnly(positions=list(range(100, 125))),
        rules.DenyResidues(amino_acids=["C"]),
        rules.FixSites(positions=[105, 120]),
        # Protect sites where the query residue is >= 95% conserved.
        rules.MSAConserved(tokenized_msa=msa, threshold=0.95),
    ],
    init_sequences=[tokens],
    # Explore up to 4 subspaces, each with at most 3 mutable sites.
    space_sampler=spaces.RandomMaskSampler(max_mutations=3, n_subspaces=4),
)
pipeline = optim.Pipeline(
    design_space=design_space,
    sampler=samplers.RandomSampler(max_samples=100),  # Propose up to 4x100 variants
    objective=predictors.PSSMZeroshotPredictor(tokens, msa, laplace_smoothing=True),
    acquisition=acquisitions.Greedy(budget=20),
)
output = pipeline.run()
# Up to 20 sequences
candidates = data.tokenizer.decode(list(output.selection.token_ids))

See the pipeline documentation for configuration options or read the concepts overview to understand Protuna's workflow and core primitives.

Storage

Protuna stores cached downloads and default pipeline artifacts under $PROTUNA_HOME/protuna. If PROTUNA_HOME is unset, it uses $XDG_CACHE_HOME/protuna, falling back to $HOME/.cache/protuna.

You can configure pipeline runs to store artifacts in another folder or directly in cloud storage (AWS, Azure, or GCP) to support large exploration campaigns.

Concepts

Protuna optimization pipeline Protuna optimization pipeline

Protuna separates candidate generation from experimental batch selection. A Pipeline combines four steps:

  1. Defining the search region. A DesignSpace holds starting sequences and their allowed substitutions and can sample smaller search spaces for independent exploration.
  2. Generating proposals. A Sampler proposes sequences within each search space.
  3. Evaluating proposals. A Predictor estimates the objective property. Hard constraints reject candidates; soft constraints provide feasibility probabilities.
  4. Selecting candidates. An Acquisition selects candidates within your budget, using criteria such as predicted fitness, uncertainty, or diversity.

Selection is limited to the candidates proposed by the sampler. Protein language models provide a useful prior over plausible sequences, but their likelihoods need not align with a campaign’s objective. Protuna supports reward-guided generation to steer exploration towards desired properties, using inference-time steering, externally aligned generators, or both.

Optional recycling uses promising candidates as parents for the next generation cycle, allowing subsequent cycles to build on promising mutations.

Read the optimization overview for the broader campaign workflow. To extend Protuna, see the guides for custom model adapters, samplers, and acquisitions.

Modules

Module Description
protuna.optim The primary optimization framework. It contains all the primitives needed to set up and run your protein optimization task.
protuna.inference Distributed inference interface and a few illustrative model adapters.
protuna.data Common preprocessed public benchmark datasets, MSA handling, and tokenization modules.
protuna.score Functional library of protein scoring methods such as zero-shot variant effect prediction (VEP) and contact prediction using a categorical Jacobian.
protuna.train (coming soon) Future releases will include trainers and recipes for few-shot property prediction models, fine-tuning, and preference alignment of generators.

Upcoming Releases

See the roadmap for upcoming releases.

Contributing

See CONTRIBUTING.md.

Citation

If you use Protuna in your research, please cite this software:

@software{protuna2026,
    title = {{Protuna: An optimization framework for AI-guided protein engineering}},
    author = {Shreshtha, Kumar},
    url = {https://github.com/kumarshreshtha/protuna},
    year = {2026},
    version = {0.1.0}
}

[^1]: Successfully generating candidates from a single data point depends on how well your goals, the zero-shot proxies you use for scoring, and the sampler's likelihoods align.