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
- query_variant_database — search stored variant triage results
- query_protein_database — search stored protein assessments
- get_knowledge_graph_stats — database health and coverage summary
- export_research_dataset — export to JSON for pandas/ML pipelines
- find_drug_gene_network — traverse the stored drug-gene-disease graph
query_variant_database
async
¶
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
¶
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
¶
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 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
¶
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).