A ranked list without a reason is a list nobody trusts

#The feature that looked finished

The first version answered the question it was built for: given an identifier, return everything related to it, ranked. It worked, the ranking was reasonable, and nobody used it.

When I sat with someone using it, the reason was immediate. The list said a valve was related to a pump with a score of 0.72. The operator's question was why, and there was no answer on the screen. With no reason to accept the ranking, they went back to the drawings.

#Four stages, and the last one matters most

Resolve. Normalise the identifier and find the node, falling back to semantic search when the literal lookup misses.

Traverse. A bounded walk over the graph, k hops, collecting the neighbourhood and the paths that reached it.

Score. Hop decay multiplied by edge confidence multiplied by a type weight, with optional centrality and semantic similarity terms. Centrality uses PageRank [1], and structural link prediction uses Adamic-Adar over shared neighbours [2].

Explain. Turn the shortest path into a sentence.

The fourth stage is why the paths are retained through traversal rather than discarded once scoring is done. Keeping them costs memory and it is the entire difference between a used feature and an ignored one.

#What an explanation looks like

Not "related, score 0.72". Instead: "measured by TT-1044, which is mounted on the same skid". That is a rendering of a two-hop path where each edge type has a human phrase attached to it.

Writing those phrases is unglamorous work. It is a string per edge type, decided once, and it converts a graph traversal into something an operator can agree or disagree with. Disagreement is valuable, since an operator saying an edge is wrong is a correction you can act on, and a score they ignore is not.

#Scoring is not the interesting part

I spent longer than I should have tuning weights. Beyond a reasonable starting point, changes to the scoring function produced smaller improvements in perceived usefulness than adding the explanation did.

The one exception is type weighting. Some edge types are structurally important and some are incidental, and a small amount of domain input on which is which outperformed every automatic method I tried.

#Where this connects to language models

A graph with explanations is a good substrate for grounded answering, because the citation is structural rather than a retrieved passage that mentions both things. Graph-based retrieval approaches exploit exactly this [4], and the property that makes them work is the same one that makes the list usable by a person: the system can say how it got there [3].