Skip to content

Precision-medicine tools

ACMG mapping is not validated

Both generate_variant_clinical_report and classify_variant_acmg use an ACMG/AMP criterion mapping that has not been reviewed by an independent clinical geneticist. Treat the output as a research aid, never as clinical decision support. See Limitations L1.

Druggability tiers are unvalidated research heuristics

assess_target_druggability and synthesize_protein_dossier report HOT, WARM, COLD, or NOT_DRUGGABLE only when at least one drug-precedent source provides an observed count in the requested development-stage scope. Otherwise the tool reports an evidence-availability error and no tier is assigned. A failed upstream request is not evidence of zero. The thresholds are author-defined, not calibrated against outcomes, and do not establish target safety or biological druggability. See Limitations L2.

Drug-precedent count semantics

The two sources count different things and are not interchangeable; both observed counts are always reported so the difference is auditable.

ChEMBL (chembl_mechanism_molecule_count): distinct molecules with a mechanism-of-action record on the single-protein ChEMBL target that carries the requested UniProt accession, at or above the requested development stage (drug_precedent_scope is approved_only when include_clinical_stage=False, otherwise approved_and_clinical, which starts at ChEMBL's Early Phase 1 (max_phase 0.5) because ChEMBL defines it as a clinical candidate in Early Phase 1 trials). The mechanism list is paginated and verified against ChEMBL's reported total; a target with more than 200 distinct mechanism-linked molecules is refused rather than truncated. ChEMBL often records a mechanism on a protein complex or family rather than the single protein (live 2026-10-28, ChEMBL 37: GABRA1/P14867 has one single-subunit mechanism while the GABA-A receptor complex target carries 66), so a ChEMBL zero does not establish that no drug engages the protein, and a mechanism record does not by itself establish direct target engagement for a given indication.

Open Targets (open_targets_drug_candidate_count): target.drugAndClinicalCandidates.count. In the deployed release probed on 2026-10-28 (API 26.9.0, data 26.09) each row is one drug record with a maxClinicalStage, and the count equalled the number of distinct drug identifiers for every probed target (BRCA1 0, TP53 9, B3GAT1 0, PARP1 13, GABRA1 76, EGFR 82). The count spans every stage, including withdrawn and unknown-stage records, and is not stage-filtered by this tool.

The tools choose the count that backs the heuristic (drug_count_source) as follows:

  1. A positive ChEMBL count in the requested scope is used as the distinct molecule count.
  2. Otherwise, when the requested scope includes clinical stages, a positive Open Targets count is credited as evidence of presence only: drug_precedent_scoring_count is 1, never three or more distinct drugs, because the record set is not stage- or mechanism-verified here.
  3. Otherwise an observed ChEMBL zero stands for the requested scope; with include_clinical_stage=False an all-stage Open Targets count cannot override an approved-only ChEMBL zero.
  4. An Open Targets zero bounds every scope and is accepted when ChEMBL has no record (live B3GAT1/Q9P2W7: no ChEMBL target, zero Open Targets records).
  5. With no observed count in the requested scope (for example ChEMBL unavailable and only all-stage Open Targets records for an approved-only request) the tool raises instead of inventing a count.

drug_count preserves the chosen source's raw count. The ChEMBL-versus- Open Targets difference is never treated as a contradiction: the sources differ in target granularity and stage scope by construction.

data_sources_status.open_targets_drug_count is skipped only when Open Targets maps no target to the accession; the dossier then does not query the Open Targets sources at all and reports them as skipped too. Ensembl and gnomAD lookups that return an explicit negative (found: false, constraint_available: false) are reported as no_data, not ok. A failed or malformed UniProt-to-Ensembl resolution is reported as failed or invalid_response, and the dossier's Open Targets sources inherit that status rather than being queried with an empty identifier. For ChEMBL, invalid_response means the client rejected the content it received (ambiguous target, unverifiable pagination, unknown molecule phase, identifier mismatch); a failed molecule request during a strict count is reported as failed, as for any other request failure. A molecule max_phase counts as observed only when it is one of ChEMBL's documented stages (4, 3, 2, 1, 0.5, -1, or the legacy preclinical 0); any other number is treated as malformed content. ChEMBL assigns -1 to a drug or clinical candidate whose clinical phase it cannot place: such a molecule is included in an approved-plus-clinical count (label "Clinical phase unknown") but makes an approved-only strict count unassessable, because it cannot be placed above or below the approval threshold. In find_drug_repurposing_candidates such a molecule is passed through to the report and counted in invalid_or_unassessed_drug_records (the result is partial) rather than being dropped at the phase threshold or truncated away by the per-target candidate limit. find_drug_repurposing_candidates applies the same split per target: chembl_lookups_failed counts request failures and chembl_lookups_invalid counts rejected source content, and either makes the candidate list incomplete.

A protein dossier also checks the supplied gene symbol against the resolved UniProt-to-Ensembl target gene symbol when mapping evidence is available. A mismatch prevents multi-gene evidence synthesis, and so does an ambiguous mapping (more than one Open Targets target matches the accession exactly). Two accession-keyed witnesses are consulted: the Open Targets mapping and the gene name on the AlphaFold DB prediction record (live 2026-10-28: P38398 BRCA1, P04637 TP53, P14867 GABRA1, P00533 EGFR). A disagreement from either witness aborts the dossier. target.identity_verified is true when at least one witness confirmed the supplied symbol, and target.identity_sources lists which. With no witness available (both sources failed or the record carries no gene name) it is false, and the symbol-keyed sources (DisGeNET, gnomAD, ClinVar, Ensembl) rest on the caller's assertion that the symbol belongs to the accession.

Recorded Open Targets identifier mapping

resolve_target uses the Open Targets mapIds GraphQL operation and accepts only an exact approved-symbol or UniProt proteinIds match on the returned Target object. tests/fixtures/opentargets_mapids_20261028.json is a sanitised capture of the deployed API (release metadata and retrieval date in its meta block) for P38398 (BRCA1), P04637 (TP53), B3GAT1 (an approved gene symbol shaped like an accession) and two identifiers that do not exist; tests/test_client_opentargets.py replays it through the client. A later schema change must be re-recorded, not assumed.

Disease-landscape counts

map_disease_drug_landscape reports counts only for the retrieved source pages (20 rows per source). total_indication_entries and total_associated_targets keep their published numeric value, the retrieved page count; the companion indication_page_complete and target_page_complete flags state whether that count is a verified source total (a page shorter than the 20-row request) or only a lower bound. The aggregates in competitive_intelligence (approved_count, pipeline_count, druggable_target_count) are page-scoped and are reported whenever every retrieved row could be classified, so on an incomplete page they are lower bounds; counts_complete is true only when both pages are complete and fully classified, false when a page is full or a row could not be classified, and null when a page could not be retrieved. Investability is assessed only when counts_complete is true. When the MONDO-keyed Open Targets lookup returns no targets and the EFO-keyed retry fails, the target list is reported as failed, the target-derived counts are null and the investability summary is NOT_ASSESSED; an empty first page followed by a failed retry is never an observed zero. A ChEMBL drug_indication response without the documented list (for example an error envelope with HTTP 200) is invalid_response, not an observed empty page. Indication rows are bucketed by ChEMBL's reported max_phase_for_ind (live ChEMBL 37, 2026-10-28: 4, 3, 2, 1, 0.5 for early phase 1, and -1 for a clinical phase ChEMBL cannot assign); 0.5 counts as early clinical pipeline. A retrieved row with -1 or a missing phase is reported in unassigned_phase_entries, and approved_count, pipeline_count and investability are withheld because the page's stage composition is not supported. Likewise, if any retrieved target row carries no tractability assessment (tractable: null), druggable_target_count is null and investability is NOT_ASSESSED, because an unknown tractability is not an observed non-tractable target.

AlphaMissense evidence status

The variant report and draft ACMG tool preserve the AlphaMissense numerical score only when a VEP-mapped substitution has a well-formed score in [0, 1]. The data_sources_status.alphamissense field distinguishes ok, no_data, failed, invalid_response, and explicit skipped_* states. In particular, missing VEP evidence (skipped_no_vep_data) does not mean AlphaMissense is biologically inapplicable; an upstream error (skipped_upstream_failed or skipped_upstream_invalid) is not absence. A failed lookup is never treated as negative or benign biological evidence.

gnomAD and gene identity

A gnomAD response flagged found: false or constraint_available: false is no_data, even if it includes other metadata. Absence must not be presented as available population or gene-constraint evidence.

gnomAD allele frequency is looked up only when the query pins one genomic allele: a versioned RefSeq coding (NM_…:c.) or genomic (NC_…:g.) HGVS expression that Ensembl VEP maps to a single GRCh38 single-nucleotide change or simple insertion/deletion, or a chrom-pos-ref-alt variant ID. The variant ID is VEP's forward-strand vcf_string, accepted only when VEP's reply names the queried expression as its input and the vcf_string agrees with VEP's own coordinates, strand and allele string. unassessed_evidence.population_frequency reports that ID, the exome and genome counts separately, and a lookup_status:

lookup_status Meaning
found gnomAD holds the variant; counts are given per cohort
no_frequency_data a response without a usable allele frequency
not_found single-nucleotide variant without a gnomAD record; site coverage is not checked
not_found_representation_unverified insertion/deletion without a record under the looked-up representation (VEP's, or the ID the caller supplied); gnomAD stores left-aligned alleles, so absence cannot be concluded
not_attempted gene-relative, protein-level, Ensembl-transcript, unversioned or multi-nucleotide input, or no single verified mapping; if the VEP request failed or its response was invalid, detail says so
failed, invalid_response the gnomAD request failed or its content was rejected

A variant without a gnomAD record is never reported as allele frequency 0. population_genetics.global_* summarise the cohort named in population_genetics.cohort (the exome cohort when gnomAD reports one, otherwise the genome cohort); the other cohort can hold carriers that the summary does not show. population_genetics.populations lists the population records of that cohort with the counts gnomAD reports. Records that split the cohort, one of its subsets or another listed record by sex (XX, XY, <record>_XX, <record>_XY, also after a subset prefix) are left out, because they count the same alleles a second time; no other record is removed. For a genome cohort gnomAD can also return populations of its HGDP and 1000 Genomes subsets (hgdp:…, 1kg:…); they are listed under those identifiers. The identifiers without a prefix already sum to the cohort, so prefixed rows must not be added to them. A cohort allele frequency is accepted only when it equals its allele count divided by its allele number; a response whose values contradict one another is reported as failed, not as a frequency. A homozygote count is passed on only as a non-negative whole number that its allele count allows: no more homozygotes than alleles and, on an autosome, where every genotype is diploid, no more than half as many. No ploidy is assumed on X or Y, and a count gnomAD does not report stays null. Allele frequency and predictor outputs carry no ACMG criterion: BA1, BS1, PM2, PP3 and BP4 are NOT_ASSESSED. tests/fixtures/variant_frequency_path_20261110.json is a sanitised capture of the live Ensembl VEP, gnomAD and AlphaFold DB responses (requests and retrieval times in its meta block) that tests/test_variant_frequency_path_recorded.py replays through the clients.

Both tools read an Ensembl VEP reply only when every hit names the queried expression as its input. A reply that names another input, or none, is reported as data_sources_status.ensembl_vep: invalid_response and nothing is taken from it: no consequence, predictor output, candidate signal, gene context or genomic mapping, and AlphaMissense is skipped_upstream_invalid. ClinVar is queried independently and is unaffected, as is the gnomAD lookup of a variant ID supplied by the caller.

For a variant that VEP places outside every transcript, functional_consequence gives the consequence terms and impact of VEP's intergenic_consequences. No transcript is named, the transcript-level fields stay empty, and no ACMG signal is derived from them.

For versioned RefSeq HGVS input, the report and ACMG research tool may recover gene context from the parenthetical input gene, an exact ClinVar transcript-text match, or an Ensembl VEP consequence explicitly linked to the queried versioned transcript, including a matching versioned xref_refseq identifier. VEP RefSeq cross-references describe aligned transcript mappings: Ensembl warns aligned transcripts may differ in sequence, exon structure and protein. These mappings support gene-level context only, never allelic equivalence, a clinical classification or a validated transcript sequence identity. Versionless, mismatched-version, overlapping-gene and unrelated-transcript cross-references are excluded. Conflicting evidence for the queried transcript still causes abstention; candidate-only ClinVar hits never establish identity.

Optional PDBe/IUCr residue annotations

Set include_literature_evidence=True on generate_variant_clinical_report, with both literature_uniprot_id (canonical UniProt accession) and literature_uniprot_residue (positive one-based reference coordinate). The default report makes no PDBe request. Missing coordinates produce an explicit status rather than a guessed mapping; upstream failures are not treated as biological absence.

The section includes PMID/PMC/DOI, sentence/exact extracted phrase, PDB entry/chain/residue, UniProt coordinate, and the NER model score. These are text-mined mentions with source-reported correspondence, not experimental validation, automatic HGVS mapping, AlphaMissense evidence, or ACMG assertions. See AFDB API compatibility and Limitations L9.

alphafold_sovereign.tools.precision_medicine

Precision-medicine MCP tools.

These tools compose multiple upstream APIs into per-call synthesis reports. They do not add scientific judgement; they assemble what the upstreams say in one place.

Tool inventory
  1. generate_variant_clinical_report — HGVS → multi-source variant report
  2. assess_target_druggability — UniProt → heuristic HOT/WARM/COLD/NOT_DRUGGABLE
  3. synthesize_protein_dossier — UniProt → multi-source briefing
  4. find_drug_repurposing_candidates — MONDO → ranked drug candidates
  5. classify_variant_acmg — HGVS → draft ACMG/AMP criteria
  6. map_disease_drug_landscape — MONDO → approved + pipeline drugs

Important caveats:

  • The ACMG/AMP criteria emitted by classify_variant_acmg and the ACMG section of generate_variant_clinical_report are a draft surface of the upstream evidence (AlphaMissense, ClinVar, gnomAD, Ensembl VEP). They are not a substitute for clinical-laboratory review and must not be used as a diagnostic.
  • The "druggability tier" returned by assess_target_druggability is a small hand-tuned heuristic (drug-precedent counts + Open Targets tractability labels + pLDDT + gnomAD LOEUF). It is not a validated predictive model.
  • The "composite repurposing score" returned by find_drug_repurposing_candidates is OT evidence × ChEMBL max clinical phase. It is a ranking aid, not an efficacy prediction.

generate_variant_clinical_report async

generate_variant_clinical_report(params: VariantClinicalReportInput) -> dict[str, Any]

Generate a multi-source variant interpretation report.

Cross-references evidence from up to seven upstream databases for a single HGVS variant into one structured research report. It preserves source classifications and computational observations separately; it does not assign an independent clinical tier or establish ACMG criteria.

  1. Ensembl VEP — functional consequence, VEP's protein-level HGVS (hgvsp), SIFT and PolyPhen predictions
  2. ClinVar — clinical pathogenicity classifications and review status
  3. gnomAD v4 — population allele frequencies (gnomAD v4, ~807k individuals)
  4. AlphaMissense — deep-learning missense pathogenicity (Cheng et al. 2023)
  5. Open Targets — disease-gene evidence scores
  6. DisGeNET — curated gene-disease association scores
  7. ChEMBL — approved drugs acting on the gene product

The report includes unassessed ACMG-related computational signals, sequence consequences, and gene-level drug context. It does not compute variant-specific three-dimensional structural impact.

gnomAD is queried only when the input pins one genomic allele: a versioned RefSeq coding (NM_…:c.) or genomic (NC_…:g.) expression that Ensembl VEP maps to a single GRCh38 single-nucleotide change or simple insertion/deletion, or a chrom-pos-ref-alt variant ID. unassessed_evidence.population_frequency gives the looked-up variant ID, the per-cohort (exome, genome) counts and an explicit lookup_status; a variant without a gnomAD record is never reported as allele frequency 0. Allele frequency and predictor scores (AlphaMissense, SIFT, PolyPhen) are returned as observations: BA1, BS1, PM2, PP3 and BP4 are NOT_ASSESSED. CADD is not retrieved: cadd_phred is always null. functional_consequence.hgvsp is VEP's protein-level HGVS expression for the canonical Ensembl transcript, such as ENSP00000350283.3:p.Cys61Gly (p.Thr125= for a synonymous change). It is empty when VEP reports none, as for an intronic or splice-site change.

Input fields

params.hgvs: HGVS expression. Gene-relative expressions discover candidate records; clinical source identity requires an exact versioned-transcript expression. params.include_population_breakdown: Include per-ancestry gnomAD data. params.include_drug_context: Include drugs acting on the gene product. params.include_literature_evidence: Query PDBe at an explicitly supplied UniProt accession and residue. The connection to the HGVS variant is NOT independently verified by this operation.

assess_target_druggability async

assess_target_druggability(params: DruggabilityInput) -> dict[str, Any]

Comprehensive druggability assessment for a protein target.

Integrates four independent druggability signals into a HOT/WARM/COLD/NOT_DRUGGABLE classification:

  1. Drug precedent — ChEMBL approved drugs + clinical compounds
  2. Tractability — Open Targets tractability labels (small-molecule, antibody, PROTAC)
  3. Structural confidence — AF2 pLDDT (model-local confidence, not binding evidence)
  4. Population constraint — gnomAD LOEUF (gene-level LoF depletion, not toxicity evidence)

This is an author-defined, uncalibrated research score, not a validated predictive model, clinical safety result, or independent biological fact.

Input fields

params.uniprot_id: UniProt accession. params.include_clinical_stage: Include Early Phase 1 through Phase III in drug count.

synthesize_protein_dossier async

synthesize_protein_dossier(params: ProteinDossierInput) -> dict[str, Any]

Generate a complete protein intelligence dossier from 7 data sources.

It assembles disease associations, drug precedent, population constraint, ClinVar variants, and cross-species orthologs for one protein into a single structured record. It composes upstream records and author-defined research heuristics, without issuing clinical conclusions.

Sources fused in parallel
  • Open Targets: disease associations + tractability + drug count
  • DisGeNET: curated GDA scores with publication counts
  • ChEMBL: approved drugs + MoA + bioactivity
  • gnomAD: population constraint (pLI, LOEUF, mis_z)
  • ClinVar: pathogenic variants in this gene
  • Ensembl: orthologs across 12 species
Input fields

params.uniprot_id: UniProt accession. params.gene_symbol: HGNC gene symbol. params.depth: 'brief' | 'standard' | 'comprehensive'.

map_disease_drug_landscape async

map_disease_drug_landscape(params: DiseaseDrugLandscapeInput) -> dict[str, Any]

Map a bounded, source-attributed therapeutic landscape for a disease.

Returns retrieved approved drugs, pipeline agents, top druggable targets, and an exploratory summary for a given MONDO disease.

Combines Open Targets evidence with ChEMBL drug indications and MONDO disease hierarchy to produce a comprehensive landscape report used in business development, competitive intelligence, and R&D portfolio decisions.

Input fields

params.disease_mondo_id: MONDO disease ID.

classify_variant_acmg async

classify_variant_acmg(params: ACMGVariantInput) -> dict[str, Any]

Generate a draft ACMG/AMP variant classification framework.

Reports computational observations that may inform an expert's later disease-specific ACMG/AMP review. This tool does NOT establish ACMG criteria or assign a pathogenicity class: generic consequence, model scores, and population frequencies are insufficient without clinical disease mechanism, inheritance, and criterion-specific validation.

Candidate signals (candidate_criteria; variant-type observations, never met criteria): PVS1 — Candidate loss-of-function consequence; mechanism not established BP7 — Synonymous consequence; splice impact not assessed

Not assessed (unassessed_evidence; raw observations, criteria NOT_ASSESSED): BA1 / BS1 / PM2 — gnomAD counts per cohort (exome, genome) for the looked-up variant ID, with an explicit lookup_status. gnomAD is queried only for a versioned NM_…:c. or NC_…:g. expression mapped to one GRCh38 single-nucleotide change or simple insertion/deletion, or a chrom-pos-ref-alt ID; a variant without a gnomAD record is never reported as allele frequency 0. PP3 / BP4 — AlphaMissense score and class, SIFT and PolyPhen as reported by their sources; no calibrated evidence strength is derived. CADD is not retrieved (cadd_phred is always null). ClinVar is returned as independent source context, not as PP5/BP6 evidence.

Input fields

params.hgvs: HGVS expression. params.inheritance_pattern: Expected inheritance mode.

find_drug_repurposing_candidates async

find_drug_repurposing_candidates(params: DrugRepurposingInput) -> dict[str, Any]

Rank existing clinical-stage drugs as repurposing candidates for a disease.

Surfaces approved or trial-stage drugs whose target carries genetic/association evidence for the disease — i.e. drug-repurposing hypotheses. For the full approved-plus-pipeline drug picture of a disease (not only repurposing candidates), use map_disease_drug_landscape instead.

How it works: take the top target_limit Open Targets evidence-scored targets for the disease; for each, fetch its ChEMBL drugs at or above min_phase; drop duplicate molecules; rank by composite_repurposing_score = OT evidence score × (max ChEMBL phase / 4). Ranking uses clinical and association evidence only — no protein structure.

Returns a JSON record whose candidates list holds up to 20 drugs (each with ChEMBL ID, name, max phase, target gene/UniProt, OT evidence score, composite score, and mechanism), plus the candidate count and the methodology string. Returns an empty candidates list with a message when the disease has no Open Targets associations. The composite score is a prioritisation aid, not an efficacy prediction — validate mechanistically before acting on it.

Input fields

params.disease_mondo_id: MONDO disease ID to repurpose against, e.g. 'MONDO:0007254' (breast carcinoma). params.target_limit: How many top OT-evidence targets to screen (1–50). params.min_phase: Minimum ChEMBL clinical phase to include (1 = Phase I, 2 = Phase II, 3 = Phase III, 4 = Approved).