Alberto-Codes / Alberto-Codes/vramfit
Enumerate the parameter-naming roots in the wild, then solve for them generally
- Dominant language
- Python
- Stars
- 1
- Forks
- 1
- Avg merge
- 5h 57m
- Merged PRs (30d)
- 110
Description
## Gap
vramfit carries four live answers to one question: which root does a
parameter name hang from? No record reconciles them, and the answer
is per target rather than general.
Measured 2026-09-05 on the #515 branch:
| Where | What it says |
|---|---|
| `docs/reference/cli.md:219` | checkpoints root at `backbone.`, maps root at `model.` |
| `tests/integration/test_torch_scan_adapter.py:329` | the scan emits `backbone.layers.0.mixer.experts.down_proj` |
| `src/vramfit/domain/sizes.py:136` | `CHECKPOINT_ROOTS` covers `backbone.` and `model.` only |
| `src/vramfit/domain/scan.py:96` | `NAME_TABLE_ROOTS` supports `transformer.` and `gpt_neox.` too (#208) |
A fifth spelling exists in tests alone. A fixture in
`tests/unit/adapters/test_row_width_routing.py` keys widths under
`transformer.`, a root no production producer emits.
The question is load-bearing, not cosmetic. #515's review spent
three separate rounds on it:
1. The pack reconciled a group's root and the plan did not. Deferred
as #550.
2. The plan refused a correct checkpoint because of that skew. Fixed
by reconciling on both sides, which closed #550 in the opposite
direction to its own proposal.
3. The shared lookup that fix created accepts a spelling no producer
emits. Skipped by maintainer ruling 2026-09-05, to be settled
here.
Two more roots wait on the same answer. #551 asks whether
`CHECKPOINT_ROOTS` gains `transformer.` and `gpt_neox.`. #552 asks
whether the reference page or the scan adapter is canonical. Both
are per-root questions this issue should make unnecessary.
## Ask
Maintainer ruling 2026-09-05: "a on the root call. we should have an
issue to ferret out the permutations in the wild and somehow solve
for them."
Two parts, and the second is the deliverable:
1. **Enumerate the permutation space.** Which roots do real
checkpoints and their loaded module trees actually use? Cover the
families vramfit already names — Llama, Nemotron-H, Gemma 4's
nested decoder, GPT-NeoX, the `transformer.` families — and state
where each root comes from: the checkpoint on disk, the loaded
torch module tree, or the GGUF the converter writes. The three
need not agree for one model, and #515 measured that they do not.
2. **Solve generally.** A per-root table is what to get away from,
not the deliverable. `CHECKPOINT_ROOTS` grows one entry per
target and `NAME_TABLE_ROOTS` grows another, and every new family
costs a ruling. Decide what replaces that: a derived root, a
canonical form every producer emits, or a reconciliation the
domain performs once and every consumer reads.
ADR-0029 decision 7 bans a prefix wildcard, and that ban stands on
measurement: #177 mapped a vision tower's `layers.5` onto the
decoder's `blk.5` and would have priced it against the wrong
columns. A general solution has to be safe in that case, which is
why this is an architecture decision and not a table edit.
## Notes
Closing this should close or reshape #551 and #552, which are the
per-root form of the same question.
Contributor guide
Research direction
Start by reading docs/reference/cli.md, src/vramfit/domain/sizes.py, src/vramfit/domain/scan.py, and the cited tests, then inspect the #515 measurements for Llama, Nemotron-H, Gemma 4, GPT-NeoX, and transformer families. Record which roots come from checkpoints, loaded module trees, and GGUF output. Done means the permutations are measured and a safe general reconciliation or canonical approach is documented, with #551 and #552 resolved or reshaped.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python, pytorch
- Domain
- machine-learning
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 28/100