# Prostt5

> Skill for protein sequence-structure translation using ProstT5 from Rostlab. Use this skill when a user wants to predict protein structure as a 3Di structural alphabet string (Foldseek tokens) from an amino acid sequence, do inverse folding (recover an amino acid sequence from a 3Di structure), embed both amino acid and 3Di sequences, or work with Foldseek-compatible structure representations. Pr…

- **Type:** Skill
- **Install:** `agentstack add skill-naity-fm4life-prostt5`
- **Verified:** Pending review
- **Seller:** [naity](https://agentstack.voostack.com/s/naity)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [naity](https://github.com/naity)
- **Source:** https://github.com/naity/FM4Life/tree/main/skills/prostt5

## Install

```sh
agentstack add skill-naity-fm4life-prostt5
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# ProstT5: Protein Sequence ↔ Structure Translation

## Overview

ProstT5 is a T5-based protein language model finetuned from ProtT5-XL-U50 to translate between amino acid (AA) sequences and **3Di structural alphabet** tokens — the same discrete structural tokens used by [Foldseek](https://github.com/steineggerlab/foldseek) for fast structure search.

**Key capabilities:**
- **AA → 3Di ("folding"):** predict structure as a 3Di string from sequence alone
- **3Di → AA ("inverse folding"):** recover amino acid sequences from 3Di structure strings
- **Embeddings:** high-quality per-residue representations for both AA and 3Di sequences

**What 3Di tokens are:** Foldseek encodes protein structure as a 20-letter structural alphabet (one token per residue). This is not 3D coordinates — it's a compact structural language. It enables fast structure-based search and comparison without full coordinate files.

**When to use ProstT5 vs ESMFold/ESM3:**
- ProstT5 outputs *3Di tokens* (useful for Foldseek search, structural alphabet analysis)
- ESMFold/ESM3 outputs *3D coordinates* (PDB format, for visualization, MD simulation, etc.)

## Installation

```bash
pip install transformers torch sentencepiece
```

## Model

| HF ID | Notes |
|---|---|
| `Rostlab/ProstT5` | Full precision |
| `Rostlab/ProstT5_fp16` | Half-precision variant (faster, recommended for GPU) |

## Critical Preprocessing Rules

ProstT5 uses a shared tokenizer for both AA and 3Di sequences:

| Sequence type | Format | Prefix token |
|---|---|---|
| Amino acids | **UPPERCASE**, space-separated, UZOB→X | `` |
| 3Di tokens | **lowercase**, space-separated | `` |

The prefix token tells the model which direction to translate. **It is required — omitting it produces wrong outputs.**

```python
import re

def preprocess_aa(sequence: str) -> str:
    """Prepare an amino acid sequence for ProstT5."""
    sequence = re.sub(r"[UZOB]", "X", sequence.upper())
    return " " + " ".join(list(sequence))

def preprocess_3di(structure: str) -> str:
    """Prepare a 3Di sequence for ProstT5."""
    return " " + " ".join(list(structure.lower()))
```

## Core Workflows

### 1. Extract Embeddings (AA sequences)

```python
import re, torch
from transformers import T5Tokenizer, T5EncoderModel

device = torch.device("cuda" if torch.cuda.is_available() else "cpu")

tokenizer = T5Tokenizer.from_pretrained("Rostlab/ProstT5", do_lower_case=False)
model = T5EncoderModel.from_pretrained("Rostlab/ProstT5").to(device)
model.half() if device.type == "cuda" else model.float()
model.eval()

sequences = ["MKTAYIAKQRQISFVK", "AGLIVHSPQWFYK"]
processed = [preprocess_aa(s) for s in sequences]
lengths = [len(s) for s in sequences]

ids = tokenizer(processed, return_tensors="pt", padding="longest",
                add_special_tokens=True).to(device)

with torch.no_grad():
    output = model(**ids)

# output.last_hidden_state shape: (batch, prefix+seq_len+EOS, 1024)
# Skip prefix token at index 0; residues are at indices [1 : seq_len+1]
for i, seq_len in enumerate(lengths):
    per_residue = output.last_hidden_state[i, 1 : seq_len + 1].float()  # (L, 1024)
    per_protein  = per_residue.mean(dim=0)                               # (1024,)
```

**Note:** Unlike ProtT5 (no prefix), ProstT5 adds a prefix token (`` or ``) at position 0. Start residue slicing at index **1**, not 0.

### 2. AA → 3Di Translation ("Folding")

Predict structure as a 3Di string from a protein sequence:

```python
from transformers import T5Tokenizer, AutoModelForSeq2SeqLM

tokenizer = T5Tokenizer.from_pretrained("Rostlab/ProstT5", do_lower_case=False)
model = AutoModelForSeq2SeqLM.from_pretrained("Rostlab/ProstT5").to(device)
model.half() if device.type == "cuda" else model.float()
model.eval()

sequences = ["MKTAYIAKQRQISFVK", "AGLIVHSPQWFYK"]
processed = [preprocess_aa(s) for s in sequences]
lengths = [len(s) for s in sequences]

ids = tokenizer(processed, return_tensors="pt", padding="longest",
                add_special_tokens=True).to(device)

gen_config = {
    "do_sample": True,
    "num_beams": 3,
    "top_p": 0.95,
    "temperature": 1.2,
    "top_k": 6,
    "repetition_penalty": 1.2,
}

with torch.no_grad():
    translations = model.generate(
        ids.input_ids,
        attention_mask=ids.attention_mask,
        max_length=max(lengths),
        min_length=min(lengths),
        early_stopping=True,
        num_return_sequences=1,
        **gen_config,
    )

decoded = tokenizer.batch_decode(translations, skip_special_tokens=True)
structure_3di = ["".join(s.split()) for s in decoded]  # remove spaces
print(structure_3di)  # list of lowercase 3Di strings, one per input sequence
```

The output is a list of 3Di strings (e.g., `"adwkcvpmaklfdeg..."`) — one character per residue, all lowercase.

### 3. 3Di → AA Translation ("Inverse Folding")

Recover amino acid sequences from 3Di structure strings:

```python
structures_3di = ["adwkcvpmaklfdeg", "strmcvpqklf"]
processed = [preprocess_3di(s) for s in structures_3di]
lengths = [len(s) for s in structures_3di]

ids = tokenizer(processed, return_tensors="pt", padding="longest",
                add_special_tokens=True).to(device)

gen_config_inv = {
    "do_sample": True,
    "top_p": 0.90,
    "temperature": 1.1,
    "top_k": 6,
    "repetition_penalty": 1.2,
}

with torch.no_grad():
    translations = model.generate(
        ids.input_ids,
        attention_mask=ids.attention_mask,
        max_length=max(lengths),
        min_length=min(lengths),
        early_stopping=True,
        num_return_sequences=1,
        **gen_config_inv,
    )

decoded = tokenizer.batch_decode(translations, skip_special_tokens=True)
aa_sequences = ["".join(s.split()) for s in decoded]
print(aa_sequences)  # recovered amino acid sequences (uppercase)
```

## Scripts

```bash
# AA → 3Di translation from FASTA
python scripts/translate.py sequences.fasta --direction aa2fold --output structures.fasta

# 3Di → AA inverse folding from FASTA
python scripts/translate.py structures.fasta --direction fold2aa --output recovered.fasta

# Generate embeddings from AA sequences
python scripts/translate.py sequences.fasta --direction embed --output embeddings.npy
```

## When to Use ProstT5 vs. Alternatives

| Goal | Recommended tool |
|---|---|
| 3Di tokens for Foldseek search | **ProstT5** |
| Sequence similarity from structure | **ProstT5** (embed 3Di) |
| 3D coordinates / PDB | ESMFold or ESM3 |
| Generative protein design | ESM3 |
| Pure AA embeddings | ProtT5 or ESM-C |

## Best Practices

- Use `ProstT5_fp16` on GPU for ~2× speed with no quality loss
- Translation is slow (0.6–2.5s per protein) because it uses autoregressive decoding; embedding is fast
- The 3Di output can be directly used as input to Foldseek for structure-based search
- For validation, compare ProstT5's 3Di output against AlphaFold2/ESMFold-predicted structures

## Resources

- **GitHub:** https://github.com/agemagician/ProtTrans
- **HuggingFace:** https://huggingface.co/Rostlab/ProstT5
- **Foldseek:** https://github.com/steineggerlab/foldseek
- **Preprint:** Heinzinger et al., 2023 — https://doi.org/10.1101/2023.07.23.550085
- **Training data:** https://huggingface.co/datasets/Rostlab/ProstT5Dataset

## References

- `references/prostt5-api.md` — detailed generation configs, batched translation, embedding 3Di sequences, integration with Foldseek

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [naity](https://github.com/naity)
- **Source:** [naity/FM4Life](https://github.com/naity/FM4Life)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** yes

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-naity-fm4life-prostt5
- Seller: https://agentstack.voostack.com/s/naity
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.