tai/taicpp/docs/fuzzy.md

FuzzyMatcher (src/util/fuzzy.h)

The one generic "which candidate did the user mean" scorer. Research: research/fuzzy-matching-selectors/ (conclusions generic-fuzzy-scorer-design, agent-model-mention-resolution). Used today by CapModelCatalog for @agent / @agent:model mentions.

Contract

Score(query, text) is in [0, 1]. 1 only for a case-insensitive exact match, 0 when nothing relates, never above 0.999 otherwise. It is the max of four signals:

Signal	Definition	Scale
Subsequence	query bytes in order inside text; DP with D = best ending in a match, M = best prefix (fzy recurrences); bonuses by the byte before the match; normalized by the perfect score 16n + 20 + 4(n-1)	1.0
Typo	1 - restricted Damerau-Levenshtein distance / max(len); insert, delete, substitute, adjacent swap cost 1	1.0
TokenTypo	best Typo against each alphanumeric token of the text	0.95
Trigram	pg_trgm: per word two leading and one trailing space, Jaccard over trigram sets	0.9

Constants (fzf algo.go)

Name	Value	Meaning
kScoreMatch	16	per matched byte
kGap	-1	per skipped byte (leading, inner, trailing)
kBonusBoundary	8	match after a non-alphanumeric byte
kBonusWhite	10	match after whitespace or at the start
kBonusCamel	7	lower to Upper, or non-digit to digit
kBonusConsecutive	4	minimum bonus for a run
kFirstMultiplier	2	first query byte bonus factor
kTrigramScale / kTokenScale	0.9 / 0.95	signal scales

Ranking and ceilings

Rank returns candidates with score > 0: score descending, then shorter text, then earlier index (fzf default tie rule). Equal matches never error. Best(query, texts, floor) returns the top index above floor or -1.

Ceiling	Value
kFuzzyQueryMax	64 bytes
kFuzzyTextMax	256 bytes
kFuzzyCandidateMax	4096 candidates

Gaps

• ASCII case folding only; non-ASCII bytes compare as-is.
• Constants are fzf's (paths), not tuned on model ids; no measurement on a real id corpus yet.
• The CAP floor (CAP_FUZZY_FLOOR 0.3) is a judgment, not a measurement.
• Tests: tests/fuzzy_test.cpp (build/fuzzy_test).