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 / PAE confidence-and-domain maps,
• a 64-dimensional topological-data-analysis (TDA) fingerprint (Betti numbers β₀, β₁, β₂ from a Vietoris-Rips filtration of Cα coordinates, computed with gudhi when the optional [tda] extra is installed; a coarse fallback without persistent homology otherwise — see _compute_lightweight_tda),
• 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),
• a geometric pocket-detection heuristic, and
• an intrinsic-disorder-region map.

All tools are read-only. Tools that require outbound HTTP fail closed when ALPHAFOLD_OFFLINE=1 (they raise AirGapError); there is no local structure cache.

Tool inventory

1. analyze_structural_confidence — pLDDT + PAE domain map
2. compute_topology_fingerprint — TDA Betti numbers (β₀, β₁, β₂)
3. compare_proteins_topologically — Pairwise fingerprint-distance matrix
4. find_evolutionary_structural_shifts — Cross-species TDA fingerprint compare
5. score_binding_pocket_geometry — Heuristic pocket detection + score
6. detect_intrinsically_disordered — IDR region map
7. get_protein_structure — Retrieve AF model metadata, URLs, coordinates

POCKET_IDEAL_RESIDUES module-attribute

POCKET_IDEAL_RESIDUES = 12.0

Residue count at/above which the size sub-score saturates.

POCKET_IDEAL_ROG_ANGSTROM module-attribute

POCKET_IDEAL_ROG_ANGSTROM = 5.0

Radius of gyration (Å) scoring peak compactness.

POCKET_ROG_TOLERANCE_ANGSTROM module-attribute

POCKET_ROG_TOLERANCE_ANGSTROM = 5.0

Å of radius-of-gyration deviation that drives the compactness sub-score to 0.

POCKET_CENTROID_OFFSET_SATURATION_ANGSTROM module-attribute

POCKET_CENTROID_OFFSET_SATURATION_ANGSTROM = 20.0

Centroid offset (Å) at/above which the offset sub-score saturates.

The sub-score rises with the pocket's offset from the structure centre. Because pockets are detected only among the inner 60 % of residues, a larger offset favours the more peripheral, solvent-accessible clefts (the common shape of a drug-binding site) over dead-central positions. This is a geometry-only prior, not a validated criterion — it does not measure solvent burial.

analyze_structural_confidence async

analyze_structural_confidence(params: UniProtInput) -> dict[str, Any]

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 max inter-residue uncertainty and PAE-derived domain boundaries - Druggability pre-screen: an ordered-fraction estimate and a structure-based-drug-design suitability flag

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 — disordered or no structure deposited

Parameters:

Name	Type	Description	Default
params.uniprot_id		UniProt accession.	required

compute_topology_fingerprint async

compute_topology_fingerprint(params: UniProtInput) -> dict[str, Any]

Compute a rotation-invariant topological fingerprint of a protein's fold.

Fetches the AlphaFold model for uniprot_id and runs persistent homology (a Vietoris-Rips filtration over the Cα point cloud) to produce a 64-dimensional fingerprint vector plus Betti numbers β₀, β₁, β₂. Use it as the per-protein input to structure-similarity comparisons: compare_proteins_topologically and find_evolutionary_structural_shifts consume these fingerprints.

The Betti numbers summarise fold topology: β₀ counts connected components (single- vs multi-domain or fragmented chains), β₁ counts loops/holes (β-barrels, large macrocycles), β₂ counts enclosed voids (cavities). Because they are invariant to rotation and translation, two orientations of the same fold produce the same fingerprint.

Returns the fingerprint vector, the Betti numbers, the residue count, 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.

Parameters:

Name	Type	Description	Default
params.uniprot_id		UniProt accession of the protein to fingerprint, e.g. 'P38398' (BRCA1).	required

compare_proteins_topologically async

compare_proteins_topologically(params: MultiProteinInput) -> dict[str, Any]

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-dimensional 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.

Applications: Possible uses (all of which require independent validation before any downstream use):

• Drug-repurposing triage: proteins with low fingerprint distance may share gross topology.
• Off-target screening: family members with near-zero distance.
• Cross-species comparison of the same gene's structure.

None of these are direct functional or sequence-similarity measures.

Parameters:

Name	Type	Description	Default
params.uniprot_ids		2–10 UniProt accessions.	required

find_evolutionary_structural_shifts async

find_evolutionary_structural_shifts(params: EvolutionaryInput) -> dict[str, Any]

Quantify cross-species structural and sequence divergence for a gene.

For each ortholog, attempts to fetch the AlphaFold structure and compute a TDA fingerprint distance against the human structure. When an ortholog structure is available in AlphaFold DB, the divergence_method is tda_fingerprint and the distance is the L2 distance between length-normalised fingerprint vectors. When the ortholog has no AlphaFold model, the method falls back to sequence_identity (1 - identity/100).

AlphaFold DB coverage of non-human proteomes is partial: model organisms (mouse, rat, zebrafish) are well-covered; others may not be. The divergence_method field on each result tells you which method was used.

Parameters:

Name	Type	Description	Default
params.gene_symbol		Human gene symbol.	required
params.target_species		List of species to compare.	required

score_binding_pocket_geometry async

score_binding_pocket_geometry(params: BindingPocketInput) -> dict[str, Any]

Identify and score putative binding pockets from AlphaFold geometry.

Detects pockets with a geometry-only heuristic. Residues in the inner 60 percent of the structure by distance from the centroid are taken as the pocket-forming core, then grown greedily into clusters within an 8 Angstrom radius. A cluster is kept as a putative pocket when it has at least min_pocket_residues members and a mean pLDDT of at least 50.

Each pocket reports a radius of gyration (compactness of the pocket residues), a centroid offset (distance of the pocket centroid from the structure centroid; larger means more peripheral — a solvent-accessible cleft rather than a dead-central cavity, and NOT a measure of solvent burial), a mean pLDDT, and a druggability index. The druggability index runs 0 to 100 and is the sum of four equally weighted 0 to 25 sub-scores: residue count, radius of gyration, mean pLDDT, and centroid offset.

This is a fast, dependency-free pre-screen, not a substitute for a validated pocket detector such as fpocket or P2Rank. It needs no ML model, is fully reproducible from AlphaFold coordinates, and runs in air-gapped deployments.

Parameters:

Name	Type	Description	Default
params.uniprot_id		UniProt accession.	required
params.min_pocket_residues		Minimum pocket size (residues).	required

detect_intrinsically_disordered async

detect_intrinsically_disordered(params: UniProtInput) -> dict[str, Any]

Map intrinsically disordered regions (IDRs) using pLDDT as proxy.

IDRs with pLDDT < 50 are predicted to be disordered in isolation by AlphaFold. This pLDDT-as-disorder-proxy approach is consistent with Ruff & Pappu (2021) and scales to the full human proteome from precomputed AlphaFold confidence.

IDR functional categories returned: - Linkers: short (< 20 aa) disordered regions between domains - Tails: N/C terminal IDRs - Long IDRs: candidate intrinsically disordered protein (IDP) segments

Clinical relevance: - IDRs are enriched for disease-causing mutations - IDRs host post-translational modification sites (phosphorylation, ubiquitination) - Long IDRs are emerging drug targets (targeted covalent inhibitors, phase separation modulators)

Reference

Ruff KM & Pappu RV. J Mol Biol. 2021;433(20):167208.

Parameters:

Name	Type	Description	Default
params.uniprot_id		UniProt accession.	required

get_protein_structure async

get_protein_structure(params: StructureRetrievalInput) -> dict[str, Any]

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 image, and the AlphaMissense substitutions CSV. 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 pockets, compute_topology_fingerprint for fold topology, and detect_intrinsically_disordered for disorder. This tool hands you the structure and its handles; it does not score or interpret the model.

Returns structure_available: false with an explanatory note when AlphaFold DB has no model for the accession — an expected coverage gap, not a server fault.

Parameters:

Name	Type	Description	Default
params.uniprot_id		UniProt accession to retrieve, e.g. 'P38398' (BRCA1).	required
params.include_coordinates		Embed the full PDB coordinate text (large); default false returns metadata and download URLs only.	required