Cite userguide answers by url, so they stop having no sources at all

[adamjohnwright]

Adam's decision. A userguide-routed question returned zero citations — "How do I use the pathway browser?" gave 0 citations and 452 tokens — because a citation carries st_id, and the userguide collection indexes documentation pages whose identity is a URL. It is also the fastest class of answer, so the gap was common rather than exotic.

The shape

Exactly one identifier per citation, the other key absent rather than empty:

{"st_id": "R-HSA-8862803", "display_name": "Deregulated CDK5 triggers..."}
{"url": "https://reactome.org/userguide/pathway-browser", "display_name": "The Pathway Browser"}

A consumer that understands only st_id keeps working by skipping what it does not recognise.

No fabricated stable ids. A made-up R- would resolve to nothing or — worse — to a real but wrong entity, and a reader cannot tell from the link text.

Deduplicated by page, not chunk: the bundle is 98 chunks across 10 pages, so chunk-level citations would repeat one page up to 27 times.

The bug the unit tests could not have caught

The first version leaked a server filesystem path as a citation url:

url   /home/awright/git/reactome_chatbot/embeddings/openai/...

source is a generic LangChain metadata field, and the CSV loaders set it to the file they read — so a Reactome document lacking an st_id cited a local path, to a public website. Only https:// and http:// sources are cited now.

It showed up the first time a real question ran. My fixtures were too clean to contain a filesystem path, which is precisely why they passed.

Measured after

question	before	after
How do I use the pathway browser?	0	4
How do I run a GSEA in Reactome?	0	2
What does CDK5 do in neurons?	12	12, no paths

CI-equivalent locally: ruff, format, mypy (129 files), full suite with no API keys set.

🤖 Generated with Claude Code