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,49 @@
+# CPython Lib/traceback.py (did-you-mean suggestions)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | fuzzy-matching-selectors |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | CPython Lib/traceback.py (did-you-mean suggestions) |
+| Source URL | https://raw.githubusercontent.com/python/cpython/main/Lib/traceback.py |
+| Source publisher / author | Python core developers |
+| Source type | repository |
+| 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
+
+The pure-Python fallback of CPython's NameError/AttributeError suggestion engine, a widely shipped 'closest name' resolver.
+
+## Key findings
+
+- Constants: _MOVE_COST 2, _CASE_COST 1 (a substitution that differs only in case), _MAX_CANDIDATE_ITEMS 750, _MAX_STRING_SIZE 40.
+- Maximum accepted distance: (len(candidate) + len(wrong_name) + 3) * _MOVE_COST // 6, additionally capped below the best distance so far.
+- Exact matches are skipped; a candidate replaces the current suggestion only on a strictly smaller distance, so ties go to the first candidate in iteration order.
+- Early exits trim common prefix/suffix, bail when the length difference alone exceeds the budget, and refuse strings over 40 characters or lists over 750 candidates.
+
+## Pros / strengths
+
+Shows that a production resolver caps candidate count and string length and resolves ties by first-seen, matching tai's static-ceiling and deterministic-tie rules.
+
+## Cons / limitations / caveats
+
+Distance-threshold design rejects far matches by construction, the opposite of 'always pick the closest'. Names only, not ids with version numbers.
+
+## Relevance to tai
+
+Confirmed ceilings (tai: 4096 candidates, 64/256 bytes) and first-wins ties. Its reject-by-threshold policy was deliberately not adopted for explicit `@agent:model`.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-25 | Initial dossier created. |