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. Each candidate includes a degree (its 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 (e.g. Parkinson's disease has no PRESENTS_DpS, Crohn's has no LOCALIZES_DlA), report the absence immediately — do not keep trying query variations. It is also the fastest way to scope an open-ended exploration.