Skip to content

Knowledge-graph tools

alphafold_sovereign.tools.knowledge_graph_tools

MCP tools for querying the local AlphaFold Sovereign Knowledge Graph.

These tools read and traverse the local SQLite knowledge graph — a genuine ACID store (WAL journalling, versioned migrations, schema v3) with foreign-key integrity across proteins, variants, diseases, drugs and their relationships.

Only explicitly stored rows are available on a fresh installation; there is no automatic biomedical seed. Older SQLite files may contain illustrative rows inserted by earlier releases: these are preserved, but must not be mistaken for independently sourced observations. The analysis tools do not write to the store on their own. On top of that store the tools provide:

  • Recall of stored entities with no upstream API call required
  • Cross-entity pattern queries ("which HIGH-tier variants share a WARM target?")
  • Batch export to JSON for pandas/ML pipelines
  • Optional provenance/audit tables (opt-in; empty by default)
Tool inventory
  1. query_variant_database — search stored variant triage results
  2. query_protein_database — search stored protein assessments
  3. get_knowledge_graph_stats — database health and coverage summary
  4. export_research_dataset — export to JSON for pandas/ML pipelines
  5. find_drug_gene_network — traverse the stored drug-gene-disease graph

query_variant_database async

query_variant_database(params: VariantQueryInput) -> dict[str, Any]

Search the local knowledge graph for stored variants.

Returns variants matching the filter criteria. No upstream API calls are made — all data is served from the local SQLite knowledge graph, which is populated only through explicit writes to the knowledge-graph storage API. Historical SQLite files may retain illustrative rows from older versions; these should not be interpreted as independently verified biology.

Input fields

params.gene: Gene symbol filter. params.tier: Clinical tier (HIGH/MEDIUM/LOW/UNKNOWN). params.clinvar_class: ClinVar classification string. params.min_am_score: Minimum AlphaMissense score. params.max_gnomad_af: Maximum gnomAD allele frequency. params.limit: Maximum results.

query_protein_database async

query_protein_database(params: ProteinQueryInput) -> dict[str, Any]

Recall proteins already stored in the local knowledge graph.

This is a local-recall query, not a live lookup: it returns only proteins that have previously been written through the knowledge-graph storage API (or retained from earlier versions of the database). No upstream API is called. To assess a protein that may not be stored yet, use assess_target_druggability (druggability tier) or analyze_structural_confidence (pLDDT), which query live sources.

Filters are combined with AND; omit a filter to leave that dimension unconstrained. Returns a JSON record with the applied query, a result_count, and the matching proteins rows. The list is empty when nothing stored matches; an empty result means the local store has no matching row, not that the protein is absent from upstream biology.

Input fields

params.druggability_tier: Keep only proteins whose stored tier equals this (HOT, WARM, COLD, or NOT_DRUGGABLE); omit for any tier. params.min_plddt: Keep only proteins whose stored mean AlphaFold pLDDT (0–100; ≥70 is high confidence) is at least this value. params.limit: Maximum rows to return (1–500).

get_knowledge_graph_stats async

get_knowledge_graph_stats() -> dict[str, Any]

Return statistics about the local knowledge graph.

Shows entity counts, database size, and last activity — useful for understanding the current contents and coverage of the local store.

export_research_dataset async

export_research_dataset(params: ExportInput) -> dict[str, Any]

Export the stored knowledge-graph data for downstream analysis.

Returns the selected tables as JSON-serialisable dicts, suitable for: - Loading into pandas DataFrames for ML feature engineering - Importing into R or Julia for statistical analysis - Feeding into downstream bioinformatics pipelines

Example (Python)::

import pandas as pd
result = await export_research_dataset(ExportInput(tables=["variants"]))
df = pd.DataFrame(result["data"]["variants"])
high_tier = df[df["clinical_tier"] == "HIGH"]
Input fields

params.tables: Tables to export (empty = the default tables; the field description lists them and every other accepted name). params.limit_per_table: Maximum rows per table.

find_drug_gene_network async

find_drug_gene_network(params: DrugNetworkInput) -> dict[str, Any]

Traverse the local knowledge graph from a seed entity.

Given a seed (UniProt ID, gene symbol, or MONDO disease ID), expands its immediate neighbourhood in the stored drug-gene-disease graph: a gene symbol resolves to its encoded proteins and reported variants, a UniProt accession resolves to its stored protein record, and a MONDO disease resolves to drugs with an indication for it. The store is populated by the storage API, or retained from historical database versions.

Input fields

params.seed: Starting entity identifier. params.max_hops: Graph traversal depth (1–3).