foldenv — per-residue structural context from AlphaFold

foldenv computes a protein residue's structural microenvironment from its AlphaFold-predicted fold: relative solvent accessibility (RSA), secondary structure (helix/strand/coil via DSSP), spatial contacts / packing, a pLDDT confidence flag, and an optional per-residue protein-language-model (PLM) embedding. One call takes a UniProt accession + residue position and returns a strict-JSON-safe dict — enough to tell a buried structural residue apart from a functional surface residue, or to featurize a mutation site for downstream ML.

from foldenv import get_structural_context

get_structural_context("P04637", 175)   # TP53 R175
# → {"uniprot_id": "P04637", "position": 175, "wildtype_aa": "R",
#    "rsa": 0.022, "secondary_structure": "C", "contact_count": 14,
#    "nearest_contacts": [...], "embedding": [...1536-d...],
#    "embedding_model": "ankh", "plddt": 96.6}

Keywords: AlphaFold · relative solvent accessibility · RSA · secondary structure · DSSP · residue contacts · contact map · pLDDT · residue microenvironment · protein language model · per-residue embedding · structural bioinformatics · mutation effect featurization.

Install

pip install foldenv
pip install "foldenv[saprot]"   # + mini3di, for SaProt's 3Di embeddings

esmc_600m additionally needs the EvolutionaryScale SDK (pip install esm), which conflicts with the pinned transformers and so belongs in its own environment.

External binary: secondary structure + RSA need the mkdssp binary (DSSP v4).

• macOS: brew tap brewsci/bio && brew install brewsci/bio/dssp
• Debian/Ubuntu: apt-get install dssp (provides mkdssp)

Without it, the low-level contact and sequence helpers still work, but every documented entry point — get_structural_context, structural_profile, tool.invoke, analysis.summarize, validation.crystal_crosscheck — needs secondary structure and so fails. PLM weights download on first use (Ankh-large ~2 GB).

Usage

Agent-tool wrapper (fast, interpretable). tool.invoke omits the raw embedding by default, so it returns quickly (no PLM download) and gives an LLM the interpretable fields:

from foldenv import tool

tool.invoke({"uniprot_id": "P04637", "position": 175})            # dict or JSON string
tool.invoke({"uniprot_id": "P04637", "position": 175, "include_embedding": True})  # +1536-d vector
tool.tool_spec("anthropic")   # tool descriptor: {name, description, input_schema}  (also "openai"/"plain")

Direct Python API. get_structural_context computes the embedding by default (loads the PLM). Pass embedding.model="none" for the structural fields only:

from foldenv import get_structural_context, config

cfg = config.load(overrides={"embedding": {"model": "none"}})   # skip the PLM forward pass
ctx = get_structural_context("P62593", 68, config=cfg)          # TEM-1 catalytic S70 (Ambler) = UniProt 68
ctx["rsa"], ctx["contact_count"], ctx["plddt"]                  # 0.052, 11, ...

Other entry points:

from foldenv import structural_profile, analysis, validation

structural_profile("P62593")                     # {pos: {aa, rsa, ss3, contact_count, plddt}} for every residue
analysis.summarize("P04637")                      # functional-site structural signature
validation.crystal_crosscheck("P62593", "1BTL")   # AlphaFold-vs-experimental agreement report

Config is overridable per call via config.load(overrides=...); all outputs are strict-JSON-safe.

Returned fields

Embedding models

embedding.EMBEDDING_MODELS registry — set embedding.model in decisions.yaml or via config.load(overrides=...):

The sequence models (Ankh, Ankh3×2, ProstT5, ESM2×2) are tested on transformers 4.27–4.45. Device is picked automatically (MPS → CUDA → CPU); ESM C is routed off MPS.

Configuration (decisions)

Defaults live in foldenv/decisions.yaml (overridable via config.load(overrides=...)): Cα-8 Å contacts (Cβ-5 Å optional), mask pLDDT < 50, RSA via Tien 2013 theoretical MaxASA, per-protein in-memory cache + optional L2 disk cache, Ankh-large embedding, mkdssp with --output-format=dssp. The on-disk cache location is ./.foldenv_cache by default, overridable via FOLDENV_CACHE_DIR or the cache.dir config leaf.

Tests

pip install -e ".[dev,saprot]"
pytest -q

Live tests self-skip when AlphaFold-DB is unreachable or mkdssp is absent; weight-loading forward-pass tests are opt-in (RUN_HEAVY_EMB=1). See tests/TESTS.md for the full inventory, and docs/SETUP_NOTES.md for environment setup and the RSA/secondary-structure validation notes.

Provenance & license

foldenv was developed inside a private research fork of MuLAN and extracted here. Two helper modules (constants.py, plm.py) adapt small routines from MuLAN — see NOTICE. Licensed under CC BY-NC-SA 4.0 (see LICENSE), the same license as MuLAN: free for attributed, non-commercial use; derivatives must share alike.

Acknowledgements

This work was carried out during a 2026 summer research internship at the Laboratoire de Biologie Computationnelle, Quantitative et Synthétique — the Laboratory of Computational, Quantitative and Synthetic Biology (CQSB, UMR 7238, CNRS–Sorbonne Université), Paris.

The internship was supported by a fellowship from the France-Stanford Center for Interdisciplinary Studies, Stanford Global Studies Division, Stanford University.