Is "naming things" hard? And if so, can one detect and measure name quality? Rhetorical question. The answer is yes.
snafu
is an agentic LLM flow to help you with "naming things" in source code.
snafu
computes the Name Ambiguity Number (NAN) for symbols in your codebase, a quantifiable score for how ambiguous the name is. Then it walks you through an agentic pipeline™ to replace it with a clearer name.
demo.mp4 #
snafu
first obtains symbols in your source file, and sends them
along the snafu
pipeline with no extra context (no function body, no docstring, no surrounding code).
Our heuristic is: reducing the ambiguity of a symbol with no extra context will also reduce it even when the symbol is back in its original context. By stripping the context away, we simulate the cognitive load of a developer reading a function with fresh eyes.
Note: Currently not all symbols are extracted. We currently try to find the most relevant symbols (by kind and hierarchy), while avoiding symbols which are often superfluous, like inline variables.
Every symbol in the file is sent to an LLM with no other context and one question: given only this name, what are the plausible, mutually-exclusive things it could mean, and how likely is each one?
The model returns a short list of interpretations with probabilities that
sum to 1. For a symbol like process_request
, that might look like:
0.55 handle an incoming request end-to-end (parse, validate, respond)
0.30 transform/normalize a request object before use elsewhere
0.15 log or record that a request occurred
Naturally, the LLM can generate interpretations and probabilities which are not correct. Yet, we believe that an LLM is a good-enough measure of semantic ambiguity for our needs.
That distribution is the raw material to generate the Name Ambiguity Number (NAN). Here's how it's built:
If an interpretation has probability p
, we obtain the Shannon Entropy of the symbol like this:
shannon_entropy(symbol) = - sum(p[i] * log2(p[i]))
This is basically "the weighted average of the number of steps one should take on a binary decision tree which identifies an outcome (the 'outcome' being the result of 'picking an interpretation')"
Yes, it's tricky. It's a bit of statistics and a bit of computer science. In simpler terms:
- If the number is
0
, there is only one possible interpretation (this is the ideal) - The higher the number, the more variance of reasonable interpretations that someone reading the symbol might choose.
NAN is actually a modification, to make it easier to reason about:
NAN(s) = 2 ** shannon_entropy(s) # aka "perplexity"
Now, if a symbol had k
equally likely interpretations, NAN = k
.
A small example:
| interpretation split | NAN |
|---|---|
| 50 / 50 | 2.00 |
| 90 / 10 | 1.38 |
| 99 / 1 | 1.06 |
All three rows have "2 interpretations," but NAN correctly reports that a 99/1
split is barely ambiguous (NAN = 1
is the ideal).
snafu
shows you each symbol's interpretations (and their probabilities) and asks which one is actually correct, or type your own description if none of them fit.
This human-in-the-loop step provides the ground truth the rest of the pipeline builds on.
For every symbol you confirmed, the LLM is given the original name and your confirmed meaning, and asked to propose a new name that expresses only that meaning, better than the previous name.
The proposed name goes through the exact same first step: getting fresh interpretations, and calculating a new NAN. This produces a NAN delta:
delta = NAN(original) - NAN(proposed)
A positive delta means the new name is less ambiguous than the old one. Any
candidate that doesn't improve (delta ≤ 0
) is dropped here.
A model reviews each surviving rename with full context: both names, the confirmed meaning, and each name's top alternative interpretation.
It checks two things: does the new name make sense on its own, and is its top interpretation matching the confirmed meaning.
This catches renames that scored well numerically but are wrong or misleading.
Finally, the information for all proposed renames are presented to the user.
- Python >= 3.14
uv
Install with uv
, from inside this repo:
uv tool install . # installs the `snafu` command on PATH
Or straight from the git repository:
uv tool install git+https://github.com/sebastiancarlos/snafu
export OPENAI_API_KEY=sk-...
export OPENAI_BASE_URL=https://my-custom-host/v1 # optional override
snafu path/to/file.py
snafu
uses the ** any-llm** library (a lightweight version of
LiteLLM) to support connecting to any LLM provider.
Pass --model
as <provider>:<model-name>
to use any supported provider. A
bare name with no prefix (e.g. gpt-4o-mini
) is treated as OpenAI.
snafu file.py --model anthropic:claude-haiku-4-5-20251001
snafu file.py --model gemini:gemini-2.5-flash
Each provider reads configuration from their own env var (OPENAI_API_KEY
,
OPENAI_BASE_URL
, ANTHROPIC_API_KEY
, ...). For the full list of supported providers, model names, and env vars, see the any-llm provider docs.
By default snafu
understands Python natively and uses Tree-sitter for symbol extraction in other languages: Ruby, C#, Java, JavaScript, TypeScript, PHP, Rust, and Go.
Tree-sitter grammars download on first use per language.
usage: snafu [-h] [--symbols-file SYMBOLS_FILE] [--dry-run]
[--min-words MIN_WORDS] [--model MODEL] [--limit LIMIT] [file]
Compute and improve "Name Ambiguity Numbers (NAN)" for symbols in source code.
positional arguments:
file source file to analyze
options:
-h, --help show this help message and exit
--symbols-file SYMBOLS_FILE
read symbols from this file, one per line, instead of
extracting them from a source file (used as-is,
--min-words not applied)
--dry-run only extract and list symbols, then exit (no LLM
calls)
--min-words MIN_WORDS
only score symbols with >= N words (default 2)
--model MODEL model to use (default gpt-4o-mini)
--limit LIMIT cap number of symbols to process
Env vars:
OPENAI_API_KEY OpenAI key (required for OpenAI models)
OPENAI_BASE_URL optional; base URL, e.g. https://my-host/v1
Other providers read their own env vars (ANTHROPIC_API_KEY, ...).
See https://docs.mozilla.ai/any-llm/providers/ for the full list.
MIT