[
https://issues.apache.org/jira/browse/CAMEL-24666?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Work on CAMEL-24666 started by Claus Ibsen.
-------------------------------------------
> camel-catalog: replace the Soundex suggestion strategy with an edit-distance
> default in camel-core-catalog
> ----------------------------------------------------------------------------------------------------------
>
> Key: CAMEL-24666
> URL: https://issues.apache.org/jira/browse/CAMEL-24666
> Project: Camel
> Issue Type: Improvement
> Components: camel-catalog, camel-jbang
> Reporter: Claus Ibsen
> Assignee: Claus Ibsen
> Priority: Major
>
> h3. Background
> The catalog validation ({{CamelCatalog.validateEndpointProperties}}, and the
> properties validation) reports unknown option names and can add "did you
> mean" suggestions through a pluggable {{SuggestionStrategy}}. The only
> implementation is {{CatalogSuggestionStrategy}} in the separate
> {{camel-catalog-suggest}} module. It is a *phonetic* matcher: it computes the
> Soundex code (Apache commons-codec, {{Soundex.US_ENGLISH_SIMPLIFIED}}) of the
> unknown name and of every known option, takes the names whose codes agree on
> all four characters, then on three, and finally a prefix match for names of
> at least four letters. commons-codec is the module's only reason to exist
> beyond the catalog API.
> h3. Problems
> * Soundex is a 1918 surname-matching algorithm (first letter plus three
> digits for consonant groups). It ignores vowels and case by design, so it
> rates unrelated option names as equal when their consonants line up, and it
> cannot see a transposed or missing letter the way edit distance does. Option
> names are camelCase identifiers, not spoken names.
> * The strategy is not installed anywhere it matters. Only
> {{camel-report-maven-plugin}} and {{camel-kamelet-main}} depend on
> {{camel-catalog-suggest}}; camel-jbang (CLI validators, the TUI's YAML
> validator and its {{tui_catalog_doc}} endpoint check, the MCP server) load
> the catalog without a strategy, so their users never get a suggestion for a
> misspelled option.
> * Because of that, camel-jbang-plugin-tui now carries its own small
> edit-distance fallback ({{TuiToolRegistry.similarNames}}) to name the closest
> options for a local AI model. One implementation in the catalog would serve
> all consumers.
> h3. Proposal
> * Add an edit-distance based strategy (Damerau-Levenshtein, case-insensitive,
> containment counts as close, threshold relative to the name length, at most
> 3-5 suggestions ranked by distance) to {{camel-core-catalog}} with no
> third-party dependency, and make it the default {{SuggestionStrategy}} of
> {{AbstractCamelCatalog}} so every catalog user gets suggestions without
> wiring.
> * Deprecate and later drop {{camel-catalog-suggest}} together with its
> commons-codec dependency (or keep it as an opt-in for those who want the
> phonetic behaviour, though nothing in the code base would use it).
> * Remove the fallback in camel-jbang-plugin-tui once the catalog provides
> suggestions itself.
> * Suggestions for unknown *component* names already exist
> ({{CamelCatalog.suggestComponentNames}}, {{CatalogTermMatcher}}); the
> option-name suggestions should use the same kind of matching so the two
> behave alike.
> h3. Why now
> AI assistants (the TUI's built-in AI with local models, and MCP clients) rely
> on the validation messages to correct themselves; a message that names the
> right option turns a retry into a fix. Edit distance is a few dozen lines and
> trivially testable, which is far easier to implement and review today than
> when the Soundex strategy was written.
> _Claude Code on behalf of davsclaus_
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
