tai/research/fuzzy-matching-selectors/github-cpython-traceback-suggestions.md

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.