Alberto-Codes / Alberto-Codes/vramfit

Enumerate the parameter-naming roots in the wild, then solve for them generally

Open
#554 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.