galaxyproject / galaxyproject/brc-analytics

Assistant: resolve organism names via catalog synonyms (lift the SRA resolver design)

Open
#1,372 0 comments 0 reactions 1 assignee Claimed by @NoopDog View on GitHub
refactor
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.