galaxyproject / galaxyproject/brc-analytics
Assistant: resolve organism names via catalog synonyms (lift the SRA resolver design)
- Dominant language
- TypeScript
- Stars
- 7
- Forks
- 11
- Avg merge
- 2d 12h
- Merged PRs (30d)
- 16
Description
## Summary
Improve organism-name matching in the assistant's organism search. **Lift the resolution design from the existing SRA work** and point it at the synonyms now in `organisms.json` (#1368), so names that aren't the current scientific name resolve to the right organism. Extend it with the enhancements below.
## Depends on
- **#1368** — the `synonyms` field in `organisms.json` (the single source this reads).
- **#1371** — organism search on the DuckDB organism instance (the surface this plugs into).
## Approach — lift the SRA design
The SRA path already solves the core: it resolves a user term through a ladder (exact taxid → name/synonym match) and echoes the resolved organism back. Lift that ladder for catalog organism search, resolving against the catalog `synonyms` (#1368). One shared resolution approach — not a second, divergent implementation. The catalog adds a few things the SRA resolver can't do (below).
## What to do
- Match the catalog `synonyms` in organism search, so "Candida auris" resolves to *Candidozyma auris* (taxid 498019); abbreviations like "TB" resolve (they're in the synonyms via #1368).
- Echo the resolved name + id back so a confident wrong-but-real resolution is visible.
## Enhancements over the SRA implementation
The SRA resolver matches exactly and, when a name maps to multiple taxids, silently picks the lowest one. The catalog resolver should go further:
- **Current-name precedence.** Prefer a match on an organism's *current scientific name* (`taxonomicLevelSpecies`) over a match on a `synonym`. So a term that is one organism's current name and another's old synonym resolves to the current-name organism — not whichever happens to have the smaller taxid.
- **Fuzzy "did you mean" fallback.** On no exact match, fall back to fuzzy matching (e.g. Jaro–Winkler / Levenshtein) and offer the closest organism as "did you mean…", instead of returning nothing on a typo.
- **Surface ambiguity.** When a term genuinely matches more than one catalog organism, present the candidates ("did you mean A or B?") rather than silently choosing one.
(Preferring an in-catalog taxon comes for free — #1368 scopes synonyms to catalog taxids, so every candidate is already in the catalog.)
**Validate against real data once #1368 lands.** Current-name precedence and surfacing ambiguity only matter when a term actually maps to more than one catalog taxon (a homonym or a synonym shared across catalog organisms). Count how often that really happens once synonyms exist. Precedence is cheap, so keep it regardless; **gate ambiguity-surfacing on a non-zero count** — if nothing real collides, drop it.
## Acceptance criteria
- [ ] "Candida auris" → *Candidozyma auris* (498019), echoed back as name + id.
- [ ] An abbreviation in the catalog synonyms (e.g. "TB") resolves to the right organism.
- [ ] Resolution reads the `organisms.json` synonyms as the single source — no separate alias dict in code.
- [ ] **Current-name precedence:** a term that is one organism's current name and another's synonym resolves to the current-name organism.
- [ ] **Fuzzy fallback:** typos fall back to "did you mean…"; unknown terms degrade, never a phantom organism.
- [ ] **Ambiguity (only if real collisions exist):** if any term maps to multiple catalog organisms, surface the candidates instead of silently picking one — otherwise drop this.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.