Skip to content

docs(asr): clarify vocabulary alias match semantics - #834

Open
CiprianSpiridon wants to merge 3 commits into
FluidInference:mainfrom
CiprianSpiridon:fix/authoritative-vocabulary-match-provenance
Open

docs(asr): clarify vocabulary alias match semantics#834
CiprianSpiridon wants to merge 3 commits into
FluidInference:mainfrom
CiprianSpiridon:fix/authoritative-vocabulary-match-provenance

Conversation

@CiprianSpiridon

@CiprianSpiridon CiprianSpiridon commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Why is this change needed?

FluidAudio's custom-vocabulary candidate API exposes both matchedAlias and similarity. The documentation currently calls matchedAlias "the exact alias," but the implementation selects the configured form with the best fuzzy string-similarity score. That wording can cause a downstream app to treat the presence of an alias as authoritative evidence and replace ordinary speech with an unrelated technical term.

This PR is documentation-only. It clarifies the existing API contract:

  • matchedAlias is the configured alias that won fuzzy ranking; its presence does not prove an exact spoken match.
  • Consumers can use similarity == 1.0 when they need to distinguish a perfect scorer result from a fuzzy result.
  • That score is path-specific and normalization-aware: compound discovery may concatenate adjacent words, while normalization may ignore case or punctuation.
  • A perfect normalized score is neither raw-text equality nor proof that applying the replacement is semantically safe.

FluidAudio remains responsible for reporting candidate evidence. Consumer applications remain responsible for replacement policy. For example, Kensi derives its own internal exact-score flag from similarity and combines it with its own collision and context rules; no Kensi-specific policy or new convenience API is added to FluidAudio.

There are no runtime, scoring, threshold, replacement, or public API changes. The final diff changes one Markdown documentation file only.

@CiprianSpiridon CiprianSpiridon changed the title feat(asr): expose authoritative vocabulary match provenance docs(asr): clarify vocabulary alias match semantics Aug 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant