Structure-intelligence tools¶
alphafold_sovereign.tools.structure_intelligence ¶
Structure-intelligence MCP tools.
These tools take raw AlphaFold structures (PDB text and PAE arrays from AlphaFold DB) and derive a small set of summaries from them:
- pLDDT and PAE confidence summaries, including the positions where near-diagonal PAE is locally elevated. Those positions are not domain boundaries, and no domain count is derived from them,
- a 64-slot exploratory Cα feature vector that holds at most 16 summary statistics. Optional GUDHI computes H₀/H₁ at the final 15-Å Vietoris-Rips filtration step and contributes eight bar-lifetime statistics for each; H₂ is not computed and the other 48 slots are zero. With GUDHI, models longer than 500 residues are reduced to 500 evenly spaced Cα atoms first. Without GUDHI, the fallback uses every residue: it fills eight slots with distance and contact statistics, one of them the 4-Å contact-graph component count, and computes no persistent homology,
- a pairwise distance matrix between TDA fingerprints (the
implementation is an L2 distance on length-normalised fingerprint
vectors — it is not an optimal-transport Wasserstein distance;
see
_fingerprint_distance), - geometric clusters of core residues with an uncalibrated geometry score. This is not a validated binding-pocket detector, and no druggability class is assigned, and
- an intrinsic-disorder-region map.
All tools are read-only. Tools that require outbound HTTP fail closed when
ALPHAFOLD_OFFLINE=1: the client raises AirGapError before a socket
is opened. The five tools that take one accession then return
retrieval_status: "request_failed", not a missing model.
compare_proteins_topologically lists each accession under
proteins_failed with the reason instead, and
find_evolutionary_structural_shifts queries Ensembl first and lets that
client's AirGapError propagate. There is no local structure cache.
Tool inventory
- analyze_structural_confidence — pLDDT + PAE confidence summary
- compute_topology_fingerprint — Exploratory Cα features; H₀/H₁ if GUDHI
- compare_proteins_topologically — Pairwise fingerprint-distance matrix
- find_evolutionary_structural_shifts — Cross-species TDA fingerprint compare
- score_binding_pocket_geometry — Core-residue clusters + geometry score
- detect_intrinsically_disordered — IDR region map
- get_protein_structure — Retrieve AF model metadata, URLs, coordinates
POCKET_IDEAL_RESIDUES
module-attribute
¶
Residue count at/above which the size sub-score saturates.
POCKET_IDEAL_ROG_ANGSTROM
module-attribute
¶
Radius of gyration (Å) scoring peak compactness.
POCKET_ROG_TOLERANCE_ANGSTROM
module-attribute
¶
Å of radius-of-gyration deviation that drives the compactness sub-score to 0.
POCKET_CENTROID_OFFSET_SATURATION_ANGSTROM
module-attribute
¶
Centroid offset (Å) at/above which the offset sub-score saturates.
The sub-score rises with the cluster's offset from the model centre, so among the core residues it ranks more peripheral clusters higher. This is an uncalibrated prior: it measures neither solvent access nor burial, and it does not indicate ligand binding.
analyze_structural_confidence
async
¶
Analyze AlphaFold structural confidence using pLDDT and PAE.
Returns a structural reliability summary (not a per-residue profile):
- pLDDT: the model's mean confidence (AlphaFold DB globalMetricValue)
plus a coarse confidence tier
- PAE (predicted aligned error): mean and maximum; up to five
residue pairs more than 10 positions apart with PAE above 15 Å
(one-based model indices); and local_high_pae, the approximate
zero-based model indices where a run of locally elevated
near-diagonal PAE begins (a short stretch much less certain than
the model as a whole, such as a flexible tail or linker)
- Domains: NOT assessed. Near-diagonal PAE does not locate domain
boundaries; the legacy domain_boundaries block is kept for
existing clients with n_putative_domains null and no candidate
positions
- Druggability pre-screen: model confidence limitations; actual
ordered fraction and ligand suitability are NOT assessed
pLDDT interpretation
90: Very high confidence — likely correct at backbone + sidechain level 70–90: High confidence — backbone correct, some sidechain uncertainty 50–70: Low confidence — may be IDP or novel fold < 50: Very low model confidence; does not establish disorder
Input fields
params.uniprot_id: UniProt accession.
compute_topology_fingerprint
async
¶
Compute an exploratory, rotation-invariant Cα summary vector for an AlphaFold model.
Fetches the AlphaFold model for uniprot_id and derives an
exploratory 64-slot feature vector from its Cα coordinates. With GUDHI
installed, H0 and H1 are computed on the 15-Å Vietoris-Rips 2-skeleton
and the vector holds 16 summary statistics of their finite bar
lifetimes (eight each); the other 48 slots are zero. H2 is NOT
computed. On this GUDHI path, models longer than 500 residues are
reduced to 500 evenly spaced Cα atoms first, so their Betti numbers
and statistics describe that subsample (subsampled is then true).
Without GUDHI the fallback uses every residue, with no subsampling:
the vector holds eight distance and contact statistics, one of them a
4-Å contact-graph component count, and no persistent homology is
computed.
Betti numbers describe this chosen filtration, not protein domains,
β-barrels, drug cavities, molecular function, or an experimental structure.
Returns the fingerprint vector and its slot layout, the Betti numbers, the
residue counts, and which method ran. Full persistent homology needs the
optional [tda] extra (gudhi); without it a coarse fallback runs that
does NOT compute persistent homology, and the result flags this. Returns a
no-structure result when AlphaFold DB has no model for the accession. This is
a coarse, geometry-only summary — not a substitute for sequence alignment,
RMSD, or functional-homology assessment.
Input fields
params.uniprot_id: UniProt accession of the protein to fingerprint, e.g. 'P38398' (BRCA1).
compare_proteins_topologically
async
¶
Compare multiple proteins using a TDA-fingerprint distance.
Computes a pairwise distance matrix between the TDA fingerprints of
the provided proteins. Distance metric: L2 distance between
length-normalised 64-slot fingerprint vectors (see
_fingerprint_distance). Distance = 0 means identical
fingerprints; larger values mean more divergent fingerprints. This
is not a Wasserstein distance between persistence diagrams.
The vectors hold at most 16 statistics (see
compute_topology_fingerprint). With GUDHI (the optional [tda]
extra), a model longer than 500 residues is compared on
500 evenly spaced Cα atoms. Without GUDHI the fallback uses every
residue of every model, with no subsampling, and builds each model's
full pairwise distance matrix, so its cost grows with the square of
the model length. protein_metadata reports n_residues_used and
subsampled for each model. In an internal audit of 23 AlphaFold
models run with GUDHI, nearly all of each normalised vector lay in
its two total-persistence components, so the distance mostly tracks
one ratio: total H1 over total H0 persistence. It has no validated
threshold for fold similarity and is not a functional,
sequence-similarity or binding-site measure (LIMITATIONS.md L12).
Input fields
params.uniprot_ids: 2–10 UniProt accessions.
find_evolutionary_structural_shifts
async
¶
Report ortholog sequence identity and exploratory structural distances.
Distances between Cα-derived feature vectors are not calibrated evolutionary, functional, binding, or antibody cross-reactivity measures. The GUDHI and geometric-proxy methods are distinguished in each result. There is deliberately no cross-method conservation ranking.
score_binding_pocket_geometry
async
¶
Cluster the core residues of an AlphaFold model by geometry.
Not a validated binding-pocket detector; no druggability class is
assigned. Cα atoms closer to the model centroid than the 60th
percentile of centroid distances are grouped greedily: in sequence
order, each unassigned core residue seeds a cluster of the unassigned
core residues within 8 Å of it. A cluster is reported when it has at
least min_pocket_residues members and a mean pLDDT of at least 50.
No cavity, solvent-accessible surface or ligand is computed.
Each of up to 10 clusters reports its residue numbers, mean pLDDT,
radius of gyration, centroid offset from the model centroid, and
geometry_score: an uncalibrated 0 to 100 sum of four equally
weighted sub-scores (residue count, radius of gyration, mean pLDDT,
centroid offset) that only orders the clusters.
estimated_volume_angstrom3 is the volume of a sphere with the
cluster's radius of gyration, not a cavity volume.
Validation status: in an internal audit of 19 AlphaFold models the
top-ranked cluster was enriched for the PDBe-KB ligand-binding site in
4 of the 18 proteins that had one, and every reported cluster scored
55 or more (LIMITATIONS.md L11). For existing clients the same
clusters are also returned under the earlier names, as deprecated
aliases: putative_pockets and n_pockets_found, with entries
keyed pocket_id, druggability_index and
druggability_components; their druggability_label is
NOT_ASSESSED. To locate binding sites, use a dedicated pocket
detector such as fpocket or P2Rank.
Input fields
params.uniprot_id: UniProt accession of the AlphaFold model to cluster, e.g. 'P24941' (CDK2). params.min_pocket_residues: Minimum cluster size, 3 to 20 (default 4).
detect_intrinsically_disordered
async
¶
Flag low-confidence modeled regions as intrinsic-disorder candidates.
Reads per-residue AlphaFold pLDDT from PDB C-alpha records and groups contiguous runs below 50. Low pLDDT may reflect intrinsic disorder, missing binding partners, alternate conformations, or model uncertainty; it is NOT independent evidence that a region is disordered.
Returns model-local residue indices, observed PDB chain/residue identifiers, and positional descriptions of low-pLDDT runs. These labels describe model geometry, not validated linkers, tails, disorder or function. Legacy idr_fraction and disordered_residue_count remain deprecated numeric aliases of low-pLDDT measurements, NOT validated intrinsic-disorder assays. Prefer low_plddt_* fields for scientific interpretation. PDB numbering is not mapped to full-length UniProt via SIFTS here.
This implementation is a reproducible screening heuristic, not a validated disorder predictor, biomolecular mechanism classifier, or clinical result. For background on intrinsic disorder, see Ruff & Pappu (2021), J Mol Biol. 433:167208; that paper does not validate these cutoffs or code.
Input fields
params.uniprot_id: UniProt accession.
get_protein_structure
async
¶
Retrieve a protein's AlphaFold model: metadata, download URLs, optional coordinates.
The single entry point for getting the predicted structure itself. Returns the
AlphaFold DB entry metadata — entry ID, model version and creation date,
organism, gene, UniProt description, the amino-acid sequence and its length, and
the model's mean pLDDT — plus stable download URLs for the PDB and mmCIF
coordinate files, the PAE matrix, and the AlphaMissense substitutions
CSV. The PAE image URL is only present in legacy API responses. Set include_coordinates to embed the full PDB coordinate text directly.
Use the sibling structure tools for interpretation rather than retrieval, so
their scopes don't overlap: analyze_structural_confidence for a pLDDT/PAE
confidence read, score_binding_pocket_geometry for geometric clusters
of core residues (not validated pockets), compute_topology_fingerprint
for an exploratory Cα summary vector, and
detect_intrinsically_disordered for low-pLDDT intervals. This tool hands you the
structure and its handles; it does not score or interpret the model.
Returns structure_available: false when no model was retrieved, and
retrieval_status says why. no_prediction_returned: AlphaFold DB answered
without a model for the accession, an expected coverage gap. request_failed:
the request was blocked (offline mode) or failed, which is not evidence that no
prediction exists.
With include_coordinates, coordinates_pdb is the file that this same
record advertises (file_urls.pdb); no second prediction lookup is made.
coordinates_status is retrieved, no_coordinates_returned (the record
advertises no PDB file, or the file is empty) or request_failed (the request
for that file failed, HTTP 404 included). coordinates_pdb is empty unless the
status is retrieved; when it is empty, coordinates_error gives the reason.
Input fields
params.uniprot_id: UniProt accession to retrieve, e.g. 'P38398' (BRCA1). params.include_coordinates: Embed the full PDB coordinate text (large); default false returns metadata and download URLs only.