fuzzy: generic FuzzyMatcher, fuzzy @agent/@model mention resolution, research archive

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-25 18:13:20 +01:00
parent c5acc2249f
commit 0ac0584a96
80 changed files with 2615 additions and 81 deletions
@@ -0,0 +1,50 @@
+# difflib - Helpers for computing deltas (Python docs)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | fuzzy-matching-selectors |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | difflib - Helpers for computing deltas (Python docs) |
+| Source URL | https://docs.python.org/3/library/difflib.html |
+| Source publisher / author | Python Software Foundation |
+| Source type | vendor docs |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-25 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | direct page fetch |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+Official documentation of SequenceMatcher (Ratcliff/Obershelp variant) and get_close_matches.
+
+## Key findings
+
+- ratio() = 2.0*M/T; over 0.6 is a rule of thumb for close matches; quick_ratio and real_quick_ratio are upper bounds.
+- autojunk: for a second sequence of 200+ items, items above 1% frequency are junk; asymmetric.
+- get_close_matches(word, possibilities, n=3, cutoff=0.6) returns the best matches sorted by score, most similar first.
+- The algorithm finds the longest contiguous common block then recurses left and right; the docs say the base algorithm is cubic worst case, quadratic expected, and difflib's is quadratic worst case.
+- Examples: get_close_matches('appel', ['ape','apple','peach','puppy']) = ['apple','ape'].
+
+## Pros / strengths
+
+Canonical stdlib reference with a published cutoff default (0.6).
+
+## Cons / limitations / caveats
+
+Gestalt matching has no boundary or camelCase awareness and is asymmetric in its junk heuristic. The result is a heuristic, not a minimal edit.
+
+## Relevance to tai
+
+tai already contains `sequencematcher.cpp`; it was evaluated and not used for ids because it lacks boundary bonuses. The 0.6 cutoff default informed choosing a documented floor (tai: 0.3, lower on purpose, see the conclusion).
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-25 | Initial dossier created. |