---
name: protein-dossier
description: Context-specific protein design model selector and protocol recommender backed by ProteinGym's 97-model leaderboard across 217 assays.
allowed-tools: Bash(uv *, python *, python3 *, ls *, test *, shasum *)
requires_python: "3.12.x"
package_manager: uv
repo_root: .
canonical_output_dir: outputs/run_human_stability
---

# ProteinDossier Pipeline

Context-specific protein design model selector and protocol recommender, backed by ProteinGym's 97-model leaderboard across 217 assays (Notin et al., NeurIPS 2024). Ranks models by suitability for a specific protein's function, taxa, MSA depth, and structure availability.

This skill is a **public data pipeline**: it does not train models or make fitness predictions. It compiles existing ProteinGym benchmark metrics into context-specific model recommendations with certificate-carrying provenance.

## Runtime Expectations

- Platform: CPU-only
- Python: 3.12.x
- Package manager: `uv`
- Execution time: <1 second per query
- No internet access required after environment install (derived assets are vendored; `uv sync` may fetch packages on first run)
- No external credentials required

## Step 1: Install the Locked Environment

```bash
uv sync --frozen
```

Success condition: uv completes without errors.

## Step 2: Run Forward-Mode Model Selection

```bash
uv run --frozen --no-sync protein-dossier select \
  --input inputs/select_human_stability.yaml \
  --outdir outputs/run_human_stability
```

Success condition: `outputs/run_human_stability/model_ranking.csv` exists with 97 ranked models.

Expected top-5 for Human Stability protein (structure available, high MSA):

| Rank | Model | Type | Suitability |
|------|-------|------|-------------|
| 1 | VenusREM | Structure & MSA | 0.692 |
| 2 | AIDO Protein-RAG (16B) | Structure & MSA | 0.690 |
| 3 | ProSST (K=2048) | Single seq & Structure | 0.689 |
| 4 | ProSST (K=4096) | Single seq & Structure | 0.683 |
| 5 | ProSST (K=1024) | Single seq & Structure | 0.674 |

Input YAML format:
```yaml
mode: select
function_type: Stability    # Activity, Binding, Expression, Stability, OrganismalFitness
taxa: Human                 # Human, Eukaryote, Prokaryote, Virus
msa_depth: High             # Low, Medium, High
has_structure: true          # true/false
max_models: 10              # how many to return
```

## Step 3: Run Reverse-Mode Model Profile

```bash
uv run --frozen --no-sync protein-dossier profile \
  --input inputs/profile_esm2.yaml \
  --outdir outputs/run_esm2_profile
```

Success condition: `outputs/run_esm2_profile/dimension_scores.csv` exists with per-dimension performance.

## Step 4: Run Protocol Mode

```bash
uv run --frozen --no-sync protein-dossier protocol \
  --input inputs/protocol_binder_design.yaml \
  --outdir outputs/run_binder_protocol
```

Success condition: `outputs/run_binder_protocol/pipeline.csv` exists with recommended tools for each design stage.

## Step 5: Verify Deterministic Reproduction

```bash
uv run --frozen --no-sync protein-dossier verify \
  --generated outputs/run_human_stability \
  --golden tests/golden_select
```

Success condition: JSON output contains `"ok": true`.

## Step 6: Run Full Demo Pipeline

```bash
uv run --frozen --no-sync protein-dossier demo
```

Runs all three modes (select, profile, protocol) in one shot.

## Step 7: Confirm Required Artifacts

Required files in `outputs/run_human_stability/`:
- `model_ranking.csv` — 97 models ranked by context-specific suitability
- `certificate.json` — audit trail with input hashes, scoring formula, per-model breakdown
- `summary.md` — human-readable model recommendations

Required files in `outputs/run_esm2_profile/`:
- `dimension_scores.csv` — per-dimension performance (function, taxa, MSA, structure)
- `certificate.json` — audit trail
- `summary.md` — model strengths/weaknesses summary

Required files in `outputs/run_binder_protocol/`:
- `pipeline.csv` — recommended tool for each design stage with evidence model
- `certificate.json` — audit trail
- `summary.md` — end-to-end protocol recommendation

## Available Inputs

| File | Mode | Description |
|------|------|-------------|
| inputs/select_human_stability.yaml | select | Human, Stability, structure, high MSA |
| inputs/select_virus_binding.yaml | select | Virus, Binding, no structure, low MSA |
| inputs/ctx_prokaryote_activity.yaml | select | Prokaryote, Activity, structure, high MSA |
| inputs/ctx_eukaryote_expression.yaml | select | Eukaryote, Expression, no structure, low MSA |
| inputs/ctx_human_binding.yaml | select | Human, Binding, structure, medium MSA |
| inputs/ctx_human_fitness.yaml | select | Human, OrganismalFitness, no structure, medium MSA |
| inputs/profile_esm2.yaml | profile | ESM2 (650M) model profile |
| inputs/protocol_binder_design.yaml | protocol | Binder design for Human IL-6R |
| inputs/protocol_enzyme_engineering.yaml | protocol | Enzyme engineering for E. coli TEM-1 |

## Scoring Formula

```
suitability(model, protein) =
    0.30 * perf_function_type(model) +
    0.25 * perf_taxa(model) +
    0.20 * perf_msa_depth(model) +
    0.15 * struct_bonus(model) +
    0.10 * overall_rank_normalized(model)
```

Weights are configurable per query.

## Data Source

ProteinGym (Notin et al., NeurIPS 2024):
- 97 protein fitness prediction models
- 217 deep mutational scanning assays
- 19 performance dimensions (5 function types, 4 taxa, 3 MSA depths, plus overall)
- No modifications to original benchmark values

## Scientific Boundary

This skill does **not** make fitness predictions or design proteins. It recommends which models to use based on published benchmark performance. Recommendations are hypothesis-generating, not validated against experimental outcomes.

## Determinism Requirements

- No randomness
- Stable sort order (suitability descending, model name for ties)
- No timestamps in scored outputs
- 47 automated tests verify all three modes, golden-file SHA256 identity, and deterministic reproduction