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:
- A positive ChEMBL count in the requested scope is used as the distinct molecule count.
- Otherwise, when the requested scope includes clinical stages, a positive
Open Targets count is credited as evidence of presence only:
drug_precedent_scoring_countis 1, never three or more distinct drugs, because the record set is not stage- or mechanism-verified here. - Otherwise an observed ChEMBL zero stands for the requested scope; with
include_clinical_stage=Falsean all-stage Open Targets count cannot override an approved-only ChEMBL zero. - 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).
- 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
- generate_variant_clinical_report — HGVS → multi-source variant report
- assess_target_druggability — UniProt → heuristic HOT/WARM/COLD/NOT_DRUGGABLE
- synthesize_protein_dossier — UniProt → multi-source briefing
- find_drug_repurposing_candidates — MONDO → ranked drug candidates
- classify_variant_acmg — HGVS → draft ACMG/AMP criteria
- map_disease_drug_landscape — MONDO → approved + pipeline drugs
Important caveats:
- The ACMG/AMP criteria emitted by
classify_variant_acmgand the ACMG section ofgenerate_variant_clinical_reportare 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_druggabilityis 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_candidatesisOT evidence × ChEMBL max clinical phase. It is a ranking aid, not an efficacy prediction.
generate_variant_clinical_report
async
¶
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.
- Ensembl VEP — functional consequence, VEP's protein-level HGVS
(
hgvsp), SIFT and PolyPhen predictions - ClinVar — clinical pathogenicity classifications and review status
- gnomAD v4 — population allele frequencies (gnomAD v4, ~807k individuals)
- AlphaMissense — deep-learning missense pathogenicity (Cheng et al. 2023)
- Open Targets — disease-gene evidence scores
- DisGeNET — curated gene-disease association scores
- 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
¶
Comprehensive druggability assessment for a protein target.
Integrates four independent druggability signals into a HOT/WARM/COLD/NOT_DRUGGABLE classification:
- Drug precedent — ChEMBL approved drugs + clinical compounds
- Tractability — Open Targets tractability labels (small-molecule, antibody, PROTAC)
- Structural confidence — AF2 pLDDT (model-local confidence, not binding evidence)
- 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
¶
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 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
¶
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
¶
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).