spoke-knowledge-graph

Use this skill whenever the user wants to explore relationships between biomedical entities — diseases, genes, drugs/compounds, proteins, pathways, anatomy, cell types, side effects, symptoms, biological processes — in the SPOKE knowledge graph (a 43M-node Neo4j graph queried with Cypher).

The golden workflow (do this every time)

1. Schema once. Call get_spoke_schema a single time at the start. It returns a compact node table + an edge_directory of Source →REL→ Target (count) with cost flags. It is cached — do not call it again unless you suspect the schema changed (then pass refresh=true). Use the edge_directory to pick the exact relationship type that connects two entity types.

2. Resolve names before querying. NEVER hand-type a node name into a MATCH. Call resolve_entity("<name or id>", label="<Type>") first. Exact {name: …} matching in SPOKE is case-sensitive ("Warfarin" not "warfarin", "asthma" not "Asthma"), and names often contain apostrophes ("Parkinson's disease"). resolve_entity returns the canonical {label, name, identifier} and also resolves synonyms/brand names and identifiers (DOID, Entrez, Ensembl, DrugBank, UMLS CUI, UBERON, GO). Pick the best candidate and say which one you chose.

3. Query by the resolved value, using parameters. Pass string literals through the parameters argument, never inline them:

   query_spoke(
     cypher_query="MATCH (d:Disease {name:$n})-[:ASSOCIATES_DaG]->(g:Gene) RETURN g.name AS gene LIMIT 20",
     parameters={"n": "multiple sclerosis"}
   )
   

   This eliminates case/quoting errors entirely. Matching by identifier (e.g. {identifier:$id}) is equally good — but note Gene.identifier is an integer (Entrez); match genes by their name (HGNC symbol) instead. Ambiguous candidate lists may include degree (the number of relationships). When an entity has several variant nodes (e.g. "glucose" deg 7 vs the canonical high-degree node), prefer the higher-degree one — especially if a traversal on your first pick is empty.

4. Interpret + surface assumptions. Explain the biological meaning, and state which node you resolved to (name + identifier), which relationship/direction you traversed, and any limitation (e.g. "SPOKE has no LOCALIZES edge for this disease").

When a query returns 0 rows, or for "how is X connected / what is near X" questions, call describe_node. It lists the relationship types a node actually has (with direction, neighbour label, and count). If the edge you expected isn't there and truncated is false, report its absence from the graph. If truncated is true, the tool returned only the largest 60 groups: check the specific edge with an anchored query before concluding absence. Graph absence is not evidence of biological absence. It is also the fastest way to scope an open-ended exploration.